Developers Digest

AI Code Review Is the New Bottleneck

Developers Digest — Sat, 16 May 2026 00:00:00 GMT

The AI coding story has moved from "can it write code?" to "can we review the amount of code it writes?" That is the more useful question in 2026. [Claude Code](/blog/what-is-claude-code-complete-guide-2026), [Codex](/blog/openai-codex-guide), Cursor, Copilot, and terminal agents can all produce working diffs quickly. The weak point is no longer generation. The weak point is the review queue behind it. Two recent research signals make the pattern hard to ignore. The arXiv paper [Debt Behind the AI Boom](https://arxiv.org/abs/2603.28592) studied 302.6k verified AI-authored commits across 6,299 GitHub repositories and found 484,366 distinct introduced issues. Code smells made up 89.3 percent of the total, and 22.7 percent of tracked AI-introduced issues still survived at the latest repository revision. Then [Coding Agents Don't Know When to Act](https://arxiv.org/abs/2605.07769) tested whether agents abstain when a reported issue has already been fixed. Even recent models still proposed unnecessary code changes in 35 to 65 percent of no-change tasks. The paper calls this action bias. In normal team language: the agent wants to do something, even when the correct move is to leave the code alone. That connects directly to what developers keep debating on Hacker News, in issue trackers, and in AI tool changelogs: coding agents are impressive, but they create a new kind of review debt. The team gets more code, more diffs, more generated tests, more "looks right" explanations, and more pressure to merge. The take: the winning AI development workflow is not the one that generates the most code. It is the one that makes agent output easiest to reject, verify, and maintain. ## The Review Problem Got Bigger Traditional code review assumed human-paced output. A developer writes a branch. Another developer reviews the diff. CI runs. Maybe a staff engineer looks at the architecture. The whole workflow is built around the idea that code creation is slow enough for review to keep up. Agents break that assumption. You can now ask one agent to write the feature, another to add tests, another to update docs, and another to handle review comments. That is useful. It is also how a small task turns into a 2,000-line pull request before lunch. The problem is not that the code is always bad. Often it works. The problem is that working code is not the same thing as maintainable code. AI agents are especially good at producing plausible glue: - extra adapters that duplicate existing helpers - tests that assert implementation details - abstractions that only serve the generated patch - verbose type guards around impossible states - "fixed" code for bugs that are no longer reproducible - documentation that describes the diff instead of the product behavior Each item is small. Together they become a maintenance tax. That is why the [agent reliability cliff](/blog/the-agent-reliability-cliff) matters. The first demo works. The tenth workflow depends on whether your system can catch subtle wrongness before it compounds. ## The Opposing View Is Fair There is a reasonable counterargument: humans also introduce technical debt. They do. A tired developer can over-abstract, copy-paste, skip tests, or patch symptoms. Code review has never been perfect. AI-generated code is not uniquely dangerous just because a model wrote it. The difference is throughput. An agent can produce more mediocre code per hour than a person can. It can also produce that code with a confident summary, a passing narrow test, and no intuitive sense that the repo is getting harder to understand. That changes the control system. If a human introduces one questionable helper, review can catch it. If an automation lane opens five AI pull requests a day, the reviewer needs better evidence than "the agent says it ran tests." This is why [Microsoft Research's April 2026 paper](https://www.microsoft.com/en-us/research/publication/to-copilot-and-beyond-22-ai-systems-developers-want-built/) is worth reading. The surveyed developers did not simply ask for more code generation. They wanted quality signals earlier in the workflow, clearer authority boundaries, provenance, uncertainty signaling, and least-privilege access. Microsoft calls the pattern bounded delegation: developers want AI to absorb surrounding assembly work without taking over the craft itself. That is the right frame. AI should not remove review. It should make review sharper. ## The New Review Stack If your team is adopting coding agents seriously, treat review as infrastructure. Not vibes. Not "one more senior engineer will skim it." Infrastructure. A practical stack has five gates. ### 1. Reproduction before patching The agent should prove the bug exists before editing. This is the direct lesson from FixedBench. If the issue is already fixed, the correct output is no diff. That has to be a valid success state in your workflow. Add a rule to your agent instructions, skills, or issue template: ```text Before patching, reproduce the reported behavior or explain why it cannot be reproduced. If the bug no longer reproduces, return a no-change report with the evidence. Do not modify code just to satisfy the task shape. ``` That rule sounds boring. It prevents a lot of useless churn. ### 2. Diff budgets Every agent task should have a rough diff budget. Small bug fix: 1 to 3 files. UI copy change: no new abstraction. Test-only improvement: no production code unless reproduction proves a bug. Migration: explicit file list and rollback note. Diff budgets are not bureaucracy. They are a way to make agent output reviewable. If the agent exceeds the budget, it should stop and explain why before continuing. This pairs well with [Codex's review-oriented workflow](/blog/codex-vs-claude-code-april-2026) and [Claude Code skills](/blog/skills-are-the-new-agent-operating-system). The tool can generate. The skill defines where it should stop. ### 3. Evidence receipts Every agent-authored change should end with a receipt: - files changed - tests run - tests not run - screenshots or browser checks for UI work - source links for factual content - risks left open - reviewer focus area This is not a status update. It is the review surface. The faster agents get, the more important receipts become. A reviewer should not have to reverse-engineer what the agent believed, which commands it ran, or where it was uncertain. ### 4. Separate reviewer passes Do not let the same agent that wrote the patch be the only reviewer. A separate reviewer can be another model, another agent harness, or a deterministic check. For code, the best reviewer is still a mix of tests, static analysis, and a human. But even an agent reviewer is useful if it receives the diff cold and is instructed to look for deletion risk, missed tests, duplicated logic, and scope creep. This is where tools like [GitHub Copilot coding agent](/blog/github-copilot-coding-agent-cli-2026), Codex cloud tasks, and Claude Code subagents start to matter. The future workflow is not "agent writes code." It is "agent writes, independent reviewer checks, CI gates, human approves." ### 5. Provenance without theater Teams need to know when a change was AI-assisted, but they do not need performative co-author spam on every commit. The useful provenance is operational: - which tool produced the diff - which prompt or issue created it - which model or agent mode was used - which tests and review gates passed - whether a human materially rewrote the result That is the point of the [AI co-author attribution debate](/blog/vscode-copilot-ai-coauthor-attribution). The weak argument is credit. The strong argument is reviewability. ## What This Means for Tool Choice The best AI coding tool is increasingly the one with the best review loop. For a solo developer, [Claude Code](/tools/claude-code) still wins when you want tight local iteration, strong planning, and project-specific skills. It is excellent when you stay close to the diff and steer the work. [Codex](/blog/openai-codex-guide) is compelling when the task is issue-shaped and you want an async branch or pull request to review later. Its product direction is clearly about delegated work returning reviewable artifacts. GitHub Copilot's advantage is distribution. If the whole team already lives in issues, pull requests, Actions, code owners, and branch protection, Copilot can fit into the system without inventing a new task surface. Cursor remains strong for visual diff control. It is still the easiest place to accept or reject generated edits line by line while your mental model is warm. The mistake is choosing by generation speed alone. Speed without review structure just moves the bottleneck. For budget planning, pair this with the [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026). Agent cost is not only token cost. It is also review cost. ## The Practical Rule Give agents permission to do less. That sounds backwards. It is not. An agent that can say "no code change needed" is safer than one that always patches. An agent that stops after a diff budget is safer than one that refactors the neighborhood. An agent that returns a receipt is more useful than one that writes a confident paragraph. The next wave of AI development will reward teams that make inaction, verification, and rejection first-class outcomes. Do not ask "how do we make agents write more code?" Ask "how do we make generated code cheap to review and easy to refuse?" That is where the leverage is now. ## Sources - [Debt Behind the AI Boom: A Large-Scale Empirical Study of AI-Generated Code in the Wild](https://arxiv.org/abs/2603.28592) - [Coding Agents Don't Know When to Act](https://arxiv.org/abs/2605.07769) - [Microsoft Research: To Copilot and Beyond: 22 AI Systems Developers Want Built](https://www.microsoft.com/en-us/research/publication/to-copilot-and-beyond-22-ai-systems-developers-want-built/) - [Ars Technica: Developers say AI coding tools work and that is precisely what worries them](https://arstechnica.com/ai/2026/01/developers-say-ai-coding-tools-work-and-thats-precisely-what-worries-them/) ## Frequently Asked Questions ### Why is AI code review becoming a bottleneck? AI coding agents can produce diffs faster than teams can inspect them. The bottleneck shifts from writing code to verifying whether the generated code is correct, scoped, maintainable, tested, and aligned with the existing codebase. ### Do AI coding agents create more technical debt? They can. The issue is not that every AI-generated change is bad. The risk is volume plus confidence. A large empirical study of AI-authored commits found persistent code smells, correctness issues, and security issues in real repositories, which means teams need stronger review gates around generated code. ### What should an AI coding agent do before editing files? It should reproduce the reported issue, inspect the relevant code path, and confirm that a change is actually needed. If the bug no longer reproduces, the agent should return a no-change report with evidence instead of modifying code. ### How do you make AI-generated pull requests easier to review? Use small task scopes, diff budgets, required tests, independent reviewer passes, and evidence receipts. The reviewer should see what changed, why it changed, what was verified, what was not verified, and where to focus. ### Should AI-generated code be labeled? Yes, but the useful label is operational provenance, not credit theater. Track which tool produced the diff, which task or prompt started it, which checks passed, and whether a human materially rewrote it. That helps reviewers and future maintainers understand the change.

Claude Agent SDK Credits End the Subscription Arbitrage

Developers Digest — Fri, 15 May 2026 00:00:00 GMT

Anthropic just drew a line through the middle of Claude Code usage. Starting June 15, 2026, the [Claude Agent SDK credit](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) separates programmatic agent usage from normal subscription usage. Agent SDK calls, `claude -p`, Claude Code GitHub Actions, and third-party Agent SDK apps draw from a new monthly credit. Interactive Claude Code in the terminal or IDE keeps using the regular subscription pool. That sounds like billing housekeeping. It is bigger than that. The era where every agent workflow could hide inside a flat subscription is ending. Coding teams now need to separate interactive work, scripted agent work, CI agents, and third-party orchestration as different budget lanes. If you have been following the [Claude Code token-burn observability problem](/blog/claude-code-token-burn-cache-observability), [agent FinOps](/blog/400-dollar-overnight-bill-agent-finops), or the rise of [terminal agents as portable runtime surfaces](/blog/terminal-agents-portable-runtime-surface), this is the same story from the pricing side. The agent runtime is maturing. The meter is catching up. ## What changed Anthropic's support article says eligible Pro, Max, Team, and Enterprise users can claim a separate monthly Agent SDK credit beginning June 15, 2026. The credit covers: - Claude Agent SDK usage in Python or TypeScript projects - `claude -p` non-interactive mode - the Claude Code GitHub Actions integration - third-party apps that authenticate through the Agent SDK It does not cover: - interactive Claude Code in the terminal or IDE - Claude conversations on web, desktop, or mobile - Claude Cowork - API-key usage from the Claude Developer Platform The published individual-plan numbers are simple: Pro gets $20, Max 5x gets $100, and Max 20x gets $200. Team and Enterprise seats have their own eligibility rules. Credits are per-user, refresh monthly, do not roll over, and do not pool across teammates. The important operational detail is what happens after the credit runs out. If extra usage is enabled, Agent SDK usage moves to standard API rates. If extra usage is not enabled, Agent SDK requests stop until the credit refreshes. ## The old mental model is wrong now The old developer mental model was: > I pay for Claude. Therefore my local agent scripts, terminal usage, CI experiments, and third-party wrappers are all basically part of the same bucket. That was always a little fuzzy. Now it is explicitly wrong. There are at least four different usage lanes: | Lane | Example | Budget posture | |---|---|---| | Interactive coding | Claude Code in a terminal or IDE | subscription usage limit | | Headless local automation | `claude -p` scripts, cron jobs, local loops | Agent SDK credit, then API-style extra usage | | CI and repository automation | Claude Code GitHub Actions, PR checks | Agent SDK credit or platform API budget | | Third-party orchestrators | Agent SDK-based apps and harnesses | Agent SDK credit or API-key billing | That distinction matters because these lanes fail differently. Interactive coding usually fails with a human present. A headless script can loop while you are away. A CI agent can run for every pull request. A third-party harness can multiply sessions across worktrees. A shared team automation can burn through individual credits in ways nobody sees until the run stops. That is why the official docs tell teams running shared production automation to use the Claude Developer Platform with an API key for predictable pay-as-you-go billing. ## The community reaction is rational The Reddit reaction is noisy, but the underlying concern is rational. Developers built real workflows around `claude -p`, Agent SDK integrations, Zed-style editor agents, OpenClaw-style harnesses, board-based orchestrators, and GitHub Actions. Many of those workflows were economically attractive because they appeared to sit near a subscription-shaped ceiling. Anthropic is now saying: interactive native use remains in the subscription lane; programmatic use gets its own credit and then behaves more like API usage. The fair complaint is predictability. A workflow that was "I have Max, let it run" becomes "I have Max, plus an SDK credit, plus possible extra usage, plus per-user non-pooled limits, plus a cutover date." The fair counterargument is also real. Autonomous workloads are not the same product as a human driving Claude Code. They can run unattended, batch tasks, power third-party apps, and create support costs that look much more like API infrastructure than chat usage. The practical take is not "Anthropic is wrong" or "users are entitled." The practical take is that agent pricing is becoming a product architecture constraint. ## What to change before June 15 Do not wait until the cutover to discover which workflows are programmatic. Start with a usage inventory: 1. Search your repos for `claude -p`, `@anthropic-ai/claude-agent-sdk`, `ClaudeSDK`, and Claude Code GitHub Actions. 2. List every third-party tool that asks you to authenticate with Claude rather than an API key. 3. Separate personal scripts from shared automation. 4. Mark which jobs can stop safely when the credit runs out. 5. Mark which jobs need API-key billing, a hard spend cap, or a different provider route. Then add receipts. Every programmatic agent run should record: - agent surface: `claude -p`, Agent SDK, GitHub Action, or third-party app - account or seat owner - model - estimated cost - input and output tokens when available - task type - repository - success or failure - stop reason - whether extra usage was enabled This is the same argument behind [agent swarms needing receipts](/blog/agent-swarms-need-receipts) and [parallel coding agents needing merge discipline](/blog/parallel-coding-agents-merge-discipline). Once agents run outside a human typing loop, a final answer is not enough. You need a billable event trail. ## The engineering pattern: separate lanes The cleanest response is to split your agent workflow into lanes. **Interactive lane.** Human-driven Claude Code sessions for exploration, refactors, and debugging. Keep this on the normal subscription path. **Personal automation lane.** Small `claude -p` scripts, local loops, and one-off helpers. Let these use the Agent SDK credit, but add local stop limits and a visible monthly ledger. **Production automation lane.** CI reviewers, nightly issue triage, deploy repair loops, and shared repo agents. Move these to API-key billing with explicit spend caps, account ownership, and logs. **Provider-routing lane.** Workflows that can run on Codex, Claude, local models, or cheaper models depending on task risk. This is where [Codex loops](/blog/codex-loops-boris-cherny-agent-routines), [OpenAI Codex managed workflows](/blog/openai-codex-cloud-security-playbook-2026), and multi-provider agent stacks become practical rather than ideological. That split avoids the worst version of the June 15 surprise: a critical automation depending on an individual user's non-pooled monthly credit. ## The opportunity There is a product opportunity hiding in the backlash. Developers do not only need cheaper usage. They need an agent budget router: - classify each run as interactive, personal automation, CI, or production - choose subscription, Agent SDK credit, API key, or alternate provider - apply a task-level budget before the first token - stop when the marginal value is gone - write a receipt that finance and engineering can both understand That is where agent tooling should go next. Not just prettier chat panes. Not just more wrappers. Budget-aware execution. The companies that win this layer will make the meter feel boring. You will know which account paid, which lane ran, why it stopped, and whether the result justified the spend. ## The take Claude Agent SDK credits are the end of subscription arbitrage for unattended coding agents. That is annoying for some workflows. It is also clarifying. Interactive Claude Code can stay a subscription product. Autonomous agent infrastructure needs budgets, ownership, metering, stop conditions, and receipts. The sooner teams model those lanes explicitly, the less painful June 15 will be. ## Sources - Anthropic Help Center: [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) - Claude Code Docs: [Legal and compliance](https://code.claude.com/docs/en/legal-and-compliance) - Anthropic: [Claude pricing](https://claude.com/pricing) - InfoWorld: [Anthropic puts Claude agents on a meter across its subscriptions](https://www.infoworld.com/article/4171274/anthropic-puts-claude-agents-on-a-meter-across-its-subscriptions.html) - Reddit: [ClaudeCode discussion of the June 15 programmatic usage change](https://www.reddit.com/r/ClaudeCode/comments/1tccd7c/its_official_anthropic_pulled_the_plug_on_all/) ## Frequently Asked Questions ### Does the June 15 change affect normal Claude Code usage? Not for interactive Claude Code in the terminal or IDE. Anthropic says interactive Claude Code continues to use normal subscription usage limits. The separate credit applies to Agent SDK usage, `claude -p`, Claude Code GitHub Actions, and third-party Agent SDK apps. ### How much Agent SDK credit do Claude Pro and Max users get? Anthropic lists $20 per month for Pro, $100 per month for Max 5x, and $200 per month for Max 20x. Team and Enterprise eligibility depends on seat type. ### What happens when the Agent SDK credit runs out? If extra usage is enabled, additional Agent SDK usage moves to standard API rates. If extra usage is not enabled, Agent SDK requests stop until the monthly credit refreshes. ### Should teams use personal Claude subscriptions for CI agents? Usually no. Anthropic's own guidance says teams running shared production automation should use the Claude Developer Platform with an API key for predictable pay-as-you-go billing. ### Is `claude -p` still useful? Yes. It is still useful for personal scripts, quick audits, and local automation. The difference is that it now belongs in a metered programmatic lane, not the same mental bucket as interactive terminal work.

Claude Code Plugin URLs Turn Skills Into a Supply Chain

Developers Digest — Thu, 14 May 2026 00:00:00 GMT

Claude Code's recent releases look like maintenance notes at first glance. Look closer. The [v2.1.129 release](https://github.com/anthropics/claude-code/releases) added `--plugin-url ` so a plugin zip archive can be fetched from a URL for the current session. The same release added `skillOverrides`, made gateway model discovery opt-in, fixed cache TTL behavior, and improved PR metrics. The [v2.1.136 release](https://github.com/anthropics/claude-code/releases) added `settings.autoMode.hard_deny` for classifier rules that block unconditionally, and fixed several plugin, MCP, worktree, and plan-mode issues. That is not a flashy model launch. It is a sign that Claude Code is turning into an agent extension platform. ## The take Plugin URLs make agent workflows more portable. They also make them easier to contaminate. Once a coding agent can fetch plugins, load skills, run hooks, connect MCP servers, and remember permission choices, the extension layer becomes part of the software supply chain. It deserves the same review posture as package installs, CI actions, shell scripts, and browser extensions. This is the security side of the argument in [Claude Code 2.1.128 is an ops release](/blog/claude-code-2-1-128-mcp-ops). The product is no longer only a terminal assistant. It is an operating surface with plugins, policies, telemetry, worktrees, and tools. That is powerful. It is also where teams need rules. ## Why plugin URLs matter A URL-based plugin install is convenient for experiments, internal rollout, and temporary sessions. It also changes the threat model. Before plugins, the risky surface was mostly the model's proposed actions: edit this file, run this command, call this tool. With plugins, the risky surface expands to the instructions and tools the model inherits before it proposes anything. That means a bad plugin can shape the agent's judgment upstream: - It can add misleading skills. - It can add hooks that run at surprising times. - It can connect tools that expose too much. - It can change the agent's default workflow. - It can make a risky path look normal. This is why [agent skills need exit criteria](/blog/agent-skills-production-checklist), but also why they need source control. A skill is not just markdown once it changes behavior. ## Hard deny is the right kind of boring The `settings.autoMode.hard_deny` addition is the important counterweight. Auto modes need an absolute refusal layer. Allow lists and user-intent classifiers are useful, but production teams also need rules that block a class of action regardless of how convincingly the task is phrased. Examples: - Never publish secrets. - Never run destructive git cleanup outside an approved flow. - Never send email without approval. - Never install an unreviewed plugin from an arbitrary URL. - Never touch production data from a local agent session. That is not pessimism. It is operational design. The same pattern appears in [OpenAI Codex cloud security](/blog/openai-codex-cloud-security-playbook-2026), [agent swarms needing receipts](/blog/agent-swarms-need-receipts), and [parallel coding agents needing merge discipline](/blog/parallel-coding-agents-merge-discipline). As agent autonomy rises, policy has to move from "remember to be careful" into executable controls. ## The opposing view The fair counterargument is that this is overkill for a solo developer. If you are experimenting locally, plugin URLs are mostly a convenience. You can install a community skill pack, try it for one task, and delete it later. Heavy governance can slow down discovery. That is true. But the posture changes when the agent can touch customer code, run long sessions, create PRs, use MCP tools, or operate inside a company repo. At that point, the plugin is not a toy. It is part of the execution environment. The lightweight version of governance is enough for most teams: 1. Pin plugin sources. 2. Keep approved plugin URLs in repo docs. 3. Review plugin manifests and hooks before use. 4. Disable or hide skills that do not apply with `skillOverrides`. 5. Put unconditional blockers in hard-deny policy. 6. Log which plugins were active in the final handoff. That is not bureaucracy. It is reproducibility. ## What I would standardize For any agent plugin system, I want four surfaces visible in the final receipt: **Extension inventory.** Which plugins, skills, hooks, and MCP servers were active? **Source provenance.** Were they local, marketplace-installed, or fetched from a URL? **Permission policy.** Which actions were allowed, denied, or hard-denied? **Runtime evidence.** Which commands, tests, PRs, or deploy checks prove the plugin-assisted run behaved correctly? That receipt lets a human reviewer answer the only question that matters: did the agent produce this change under an environment we would trust again? ## The practical bottom line Claude Code plugin URLs are useful. Hard-deny rules are necessary. The two belong together. One makes agent extensions easier to distribute. The other gives teams a way to say "never, even if the task sounds reasonable." That is the next maturity layer for coding agents: not better vibes, but governed extension surfaces with auditable receipts. Sources: [Claude Code releases](https://github.com/anthropics/claude-code/releases), [Claude Code plugins docs](https://docs.anthropic.com/en/docs/claude-code/plugins), [Claude Code settings docs](https://docs.anthropic.com/en/docs/claude-code/settings), [Anthropic MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp). ## Frequently Asked Questions ### What is Claude Code `--plugin-url`? It is a Claude Code option that fetches a plugin zip archive from a URL for the current session. It makes plugins easier to try and distribute, but it also means teams should review and pin plugin sources. ### What is `settings.autoMode.hard_deny`? It is a Claude Code setting for auto mode classifier rules that block actions unconditionally. These rules are useful for non-negotiable policy boundaries such as secret exposure, destructive commands, unapproved sends, or unreviewed plugin installs. ### Are Claude Code plugins dangerous? Plugins are not inherently dangerous, but they are powerful. They can add skills, hooks, MCP servers, and behavior that affects agent execution. Treat them like other developer supply-chain inputs. ### How should teams manage agent plugins? Start with a small approved list, pin sources, review manifests and hooks, use `skillOverrides` to hide irrelevant skills, configure hard-deny rules for sensitive actions, and include active plugins in the final agent receipt.

Codex CLI Vim Mode Is an Ergonomics Signal

Developers Digest — Thu, 14 May 2026 00:00:00 GMT

The most interesting line in [Codex CLI 0.129.0](https://github.com/openai/codex/releases/tag/rust-v0.129.0) is not the biggest one. It is this: the TUI composer now supports modal Vim editing, including `/vim`, default-mode configuration, and Vim-specific keymap contexts. That sounds like a small quality-of-life feature. It is more than that. It is a sign that terminal agents are being designed for people who live inside terminals all day, not just people trying a chat demo. ## The take Agent UX is moving from chat convenience to workbench ergonomics. The old AI coding interface was a prompt box. The newer interface is a terminal runtime with diffs, resumable threads, worktrees, hooks, plugins, permissions, browser tools, and receipts. Once a tool reaches that stage, keyboard behavior is not polish. It is workflow infrastructure. That is why modal editing matters. If a developer edits prompts, plans, file paths, command notes, and review instructions inside an agent composer dozens of times a day, the composer becomes part of the coding surface. It should respect the developer's muscle memory. This fits the broader pattern in [terminal agents becoming portable runtime surfaces](/blog/terminal-agents-portable-runtime-surface), [Codex loops](/blog/codex-loops-boris-cherny-agent-routines), and [Codex `/goal` workflows](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences). The agent is not just answering. It is sitting inside the developer's control loop. ## Why this release is bigger than Vim Codex CLI 0.129.0 added more than modal editing. The release also improved resume and fork flows, raw scrollback mode, `/ide` context injection, workspace-aware `/diff`, status-line summaries, `/keymap debug`, plugin sharing controls, hook browsing, and experimental goal visibility. That cluster tells a clear story. Codex is treating the terminal as the product surface, not just the place where logs appear. The difference is practical: - Resume and fork pickers make agent work interruptible. - Workspace-aware diffs make review local and concrete. - `/ide` context injection connects editor state to terminal work. - `/keymap debug` acknowledges that terminal input is messy. - Hook browsing turns lifecycle automation into something a user can inspect. - Plugin sharing controls treat extensions as collaborative infrastructure. Those are not model capabilities. They are operational capabilities. ## The opposing view The fair opposing view is that Vim mode does not make the agent smarter. Correct. A modal composer will not fix a bad plan, hallucinated API, unsafe shell command, or weak test. Teams still need [agent receipts](/blog/agent-swarms-need-receipts), [security boundaries](/blog/openai-codex-cloud-security-playbook-2026), and [merge discipline](/blog/parallel-coding-agents-merge-discipline). But daily tools win through repeated friction reduction. A feature that saves two seconds once is not interesting. A feature that saves cognitive switching every turn becomes meaningful. That is the same reason developers care about tmux, shell history, editor keybindings, fuzzy finders, and clipboard behavior. None of those writes better code by itself. Together, they make the workbench feel native. Agents need that same maturity. ## What agent tools should copy Every terminal agent should treat input ergonomics as a first-class surface. That means: 1. Respect existing editor muscle memory. 2. Make keymaps inspectable. 3. Keep prompt editing recoverable after interrupts. 4. Let users fork and resume work without losing context. 5. Show diffs close to the conversation. 6. Let hooks and plugins be browsed before they run. 7. Expose enough status to know which branch, PR, model, and mode are active. This is especially important for long-running work. If an agent session lasts hours, the interface cannot feel like a disposable chat window. It has to feel like a dependable terminal workspace. ## The practical bottom line Codex CLI Vim mode is a small feature with a large signal. AI coding tools are entering the ergonomics phase. The winners will not only have strong models. They will make agent work feel native to the developer's existing environment: terminal, editor, keyboard, git, browser, and review loop. That is how coding agents become daily tools instead of impressive demos. Sources: [Codex CLI 0.129.0 release notes](https://github.com/openai/codex/releases/tag/rust-v0.129.0), [Codex CLI 0.130.0 release notes](https://github.com/openai/codex/releases/tag/rust-v0.130.0), [OpenAI Codex repository](https://github.com/openai/codex), [OpenAI Codex docs](https://developers.openai.com/codex/). ## Frequently Asked Questions ### What changed in Codex CLI 0.129.0? Codex CLI 0.129.0 added modal Vim editing in the TUI composer, improved resume and fork flows, added raw scrollback mode, improved `/diff`, added `/ide` context injection, expanded plugin management, and improved hooks and goal surfaces. ### Why does Vim mode matter for coding agents? It makes the agent composer feel native for developers who already use modal editing. For high-frequency agent work, prompt and plan editing are part of the coding workflow, so input ergonomics matter. ### Does modal editing improve model quality? No. Modal editing does not make the model smarter. It reduces interface friction so developers can supervise, correct, resume, and review agent work more effectively. ### What should teams look for in a terminal agent? Look for resumable sessions, visible diffs, inspectable keymaps, clear permission modes, plugin and hook visibility, branch and PR status, and receipts that explain what the agent changed and verified.

Skills for Real Engineers Need Governance, Not Fandom

Developers Digest — Thu, 14 May 2026 00:00:00 GMT

[Matt Pocock's `skills` repo](https://github.com/mattpocock/skills) is the latest proof that the agent-skills format has escaped the docs corner. The repo is popular because it does not pitch "vibe coding." It frames skills as engineering process: grilling a vague request before implementation, building shared language, using red-green-refactor loops, diagnosing failures, designing interfaces, writing PRDs, and converting product intent into issues. That is useful. It also creates a new problem. Once teams install skills from creators, vendors, coworkers, and internal repos, the question stops being "do skills work?" and becomes "who governs the instructions your agents are allowed to inherit?" ## The take Skills are becoming production controls. That means they need the same boring discipline as any other production control: ownership, versioning, review, tests, deprecation, and rollback. The existing Developers Digest posts on [agent skills needing exit criteria](/blog/agent-skills-production-checklist), [Google's skills repo](/blog/google-skills-agent-playbook), and [Karpathy-style CLAUDE.md rule sets](/blog/karpathy-claude-md-skills-menu) all point in the same direction. Reusable agent instructions are not prompt lore anymore. They are part of the software supply chain. The fresh signal from `mattpocock/skills` is cultural. Developers are not just asking agents to write code faster. They are trying to transfer experienced engineering taste into repeatable procedures. That is the right move, but only if the procedures stay inspectable. ## Why this repo hit a nerve The repo names real failure modes: - The agent did not understand the work. - The agent was too verbose. - The code did not work. - The architecture drifted into a ball of mud. - The team lacked a shared language. Those are not model-selection problems. They are workflow problems. That is why a skill such as "grill me" matters. The skill is not magic wording. It forces the agent to stop and extract ambiguity before implementation. That pairs directly with the operating lesson in [long-running agents need harnesses](/blog/long-running-agents-need-harnesses): the model is only one part of the system. The task contract, feedback loop, and stop condition are where the real leverage lives. The Hacker News counterargument is also worth taking seriously. Some commenters see elaborate skills as overbuilt prompt theater. The fair version of that critique is simple: if a skill is just fancy language without measurable behavior, it should not survive. That is the governance bar. ## What governance looks like A production skill should answer five questions: 1. Who owns it? 2. Which failure mode does it reduce? 3. Which observable behavior should change when it is active? 4. Which repo, tool, or workflow is it allowed to affect? 5. When should it be deleted or rewritten? Without those answers, a skill library turns into the agent equivalent of stale wiki pages. This matters even more when skills spread across tools. The same instruction may be consumed by Claude Code, Codex, Cursor, or a custom agent runner. If the skill says "commit after every meaningful change," that is harmless in one workflow and dangerous in another. If it says "always use TDD," that might improve a backend module and slow down a throwaway spike. Good skills encode judgment. Bad skills encode superstition. ## The opposing view The strongest opposing view is that skills are just prompts with file names. There is truth in that. A markdown file does not guarantee better engineering. A popular repo does not prove a method works. And an LLM confidently praising a prompt pattern is not evidence. The right response is not to reject skills. It is to demand receipts. For every important skill, track whether it changes the work: - Did it reduce review comments? - Did it increase passing local checks? - Did it catch unclear requirements earlier? - Did it shrink final diffs? - Did it reduce abandoned agent sessions? - Did it improve handoff quality? That is the same move described in [agent replays with TraceTrail](/blog/agent-replays-with-tracetrail) and [Claude Code token-burn observability](/blog/claude-code-token-burn-cache-observability). Once an instruction affects agent behavior, it should be observable. ## What teams should copy Do not copy the whole repo into every project. Copy the operating shape: - A skill starts with a narrow trigger. - It names the failure mode. - It gives a procedure, not a vibe. - It includes stop conditions. - It asks for evidence at the end. - It stays short enough for an agent to actually use. For a product team, the first three skills I would write are not framework-specific. **Ambiguity gate.** Before implementation, force the agent to identify missing requirements, user-visible risk, and files it expects to touch. **Verification ladder.** Require the agent to choose cheap checks first, then escalate to build, browser QA, or production smoke tests when the change affects users. **Review receipt.** Require a final report with files changed, commands run, commands skipped, screenshots or URLs where relevant, and residual risk. Those three are less glamorous than a huge catalog. They also compound faster. ## The practical bottom line The skills trend is real, but the winning teams will not be the ones with the biggest `~/.claude/skills` folder. They will be the ones that treat skills as governed operating controls: small, reviewed, measured, and deleted when they stop helping. Matt Pocock's repo is a useful menu. The production lesson is to build your own kitchen. Sources: [mattpocock/skills](https://github.com/mattpocock/skills), [Hacker News discussion of the grill-me skill](https://news.ycombinator.com/item?id=47550391), [Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills), [Google skills repo](https://github.com/google/skills). ## Frequently Asked Questions ### What are AI coding skills? AI coding skills are reusable instruction files that teach an agent how to handle a recurring kind of work. In tools like Claude Code, they can describe when to ask clarifying questions, how to run tests, what evidence to return, and which project constraints matter. ### Why does a skills repo need governance? Because skills can change agent behavior across many sessions. If they are stale, too broad, or copied without review, they can make agents confidently apply the wrong process. Governance keeps skills owned, versioned, measured, and removable. ### Should teams install community skill packs? Community skill packs are useful as examples and starting points. Production teams should copy the shape, then adapt each skill to their own repo, commands, review standards, and risk profile. ### How do you know if a skill works? Measure behavior. Useful signals include fewer review comments, better test coverage, clearer final reports, fewer abandoned sessions, smaller diffs, and more reliable local verification.

Agent Memory Benchmarks Are Not Enough

Developers Digest — Wed, 13 May 2026 00:00:00 GMT

Agent memory is having its GitHub trending moment. Today, `rohitg00/agentmemory` is near the top of [GitHub Trending](https://github.com/trending), pitching persistent memory for Claude Code, Codex CLI, Cursor, Gemini CLI, and other MCP-capable coding agents. The promise is obvious: stop re-explaining the same architecture, bugs, preferences, and workflow rules every session. That is a real pain. Anyone using [Claude Code](/blog/what-is-claude-code-complete-guide-2026), [Codex](/blog/openai-codex-guide), or terminal agents long enough has hit it. The agent forgets the migration plan. It rediscovers a test command. It misses a convention you corrected yesterday. But the interesting question is not whether agents need memory. They do. The question is what kind of memory you can trust. For coding agents, retrieval accuracy is only the first benchmark. The production bar is higher: can the agent remember the right thing, forget the stale thing, show where the memory came from, and roll back a bad learning without poisoning future sessions? That is the difference between useful memory and a second hallucination surface. ## Why This Is Trending Now The trend makes sense because the agent stack has matured around it. We already have better runtime surfaces for agents, from terminal tools to managed job systems. We already have [context reduction patterns](/blog/agent-context-reduction-pattern) that keep raw logs and tool output outside the model window. We already have [skills](/blog/why-skills-beat-prompts-for-coding-agents-2026), hooks, plugins, worktrees, traces, and MCP servers. Memory is the next control plane. The `agentmemory` repo is not just a vector store wrapper. Its README claims cross-agent support, hooks, MCP tools, a local server, replayable sessions, SQLite-backed storage, benchmark reports, and a viewer. It also compares itself against Mem0, Letta, Khoj, claude-mem, and other memory systems. That broader shape is the signal. Developer memory is moving from "paste this into `CLAUDE.md`" to a runtime layer with capture, retrieval, replay, deletion, and governance. That is exactly where teams should slow down. ## The Benchmark Trap Most memory demos optimize for the happy path: 1. Save a fact. 2. Start a new session. 3. Ask a related question. 4. Watch the agent recall the fact. That proves something. It does not prove enough. The `agentmemory` README highlights LongMemEval-S retrieval numbers and token savings. Letta's docs frame memory as context-window management across core memory, recall memory, and archival memory. LangChain's memory docs split the problem into semantic, episodic, and procedural memory. Those are useful frames. But real coding agents fail in messier ways: - they retrieve a true memory that no longer applies - they mix two project conventions from different repos - they overfit to a one-off correction - they bury the source of a learned rule - they keep private or sensitive facts longer than they should - they recall "we tried X and it failed" without the conditions that made it fail - they inject too much memory and increase token burn Retrieval benchmarks reward finding stored facts. Coding work also needs contradiction handling, provenance, permissioning, and deletion. The most important memory test is not "can the agent find a fact?" It is "can the agent decide whether this fact still deserves authority?" ## Four Memory Types Teams Actually Need For developer workflows, I would separate memory into four buckets. **Project memory** is stable repo context: build commands, route structure, architecture decisions, service boundaries, design rules, and deployment quirks. This belongs in explicit files like `AGENTS.md`, `CLAUDE.md`, `DESIGN.md`, or repo docs. It should be readable, reviewed, and versioned. **Episodic memory** is what happened in a session: which bug was investigated, what failed, what test confirmed the fix, what deploy was verified. This is where replayable sessions and receipts matter. It complements [long-running agent harnesses](/blog/long-running-agents-need-harnesses) because the agent can resume from evidence, not vibes. **Procedural memory** is how the agent should do work: review checklists, handoff formats, QA routines, branch discipline, and source-quality rules. This is where [self-improving skills](/blog/self-improving-skills-claude-code) are powerful because they turn corrections into auditable workflow artifacts. **User memory** is preference and personal context: tone, priorities, preferred tools, boundaries, and recurring workflows. This is valuable, but it needs the strictest deletion and visibility controls because it can easily cross from helpful into creepy or wrong. Lumping all four into "memory" makes the system harder to reason about. A source link should have different authority from a preference. A one-session debugging note should not outrank a repo instruction. A stale deploy workaround should not survive a platform migration. ## The Minimum Viable Memory Contract If you are adding memory to a coding agent, ask for a contract before you ask for a benchmark. At minimum, the memory layer should expose: - source provenance for every injected memory - memory type: project, episodic, procedural, or user - created and last-verified timestamps - confidence or authority level - scope: repo, organization, user, or global - expiration or stale-after rules - deletion paths that actually remove the memory from retrieval - review and rollback for automatically learned rules - receipts showing which memories affected a run This sounds like paperwork until it saves you from a bad day. Imagine an agent recalls "deploys use Vercel" after the project moved to Coolify. If the memory has a timestamp, source file, scope, and stale-after rule, the agent can downgrade it. If it is just an embedding in a memory store, the agent may confidently run the wrong playbook. That is why transparent memory beats clever memory for engineering teams. ## The Opposing View Is Right About One Thing The skeptical take is that agents already have too much context and too many hidden influences. Adding another retrieval layer can make them less predictable. That critique is valid. Bad memory systems create failure modes that are harder to debug than a cold-start agent. The model appears to "know" something, but the user cannot see which memory caused the behavior. A stale preference gets retrieved because it is semantically close. A low-confidence observation becomes a rule. A memory extracted from a failed session becomes future guidance. This is why I prefer memory that behaves more like Git than magic. For durable workflow knowledge, put the final form in markdown files, skills, repo instructions, or structured manifests. For episodic memory, keep session logs, summaries, and receipts. For semantic search, make retrieval visible and scoped. For automatic learning, require review above a confidence threshold. Memory should make an agent easier to inspect, not harder. ## Where `agentmemory` Looks Interesting The interesting part of `agentmemory` is not only that it stores memories. It is that it treats memory as a shared local service for multiple agents. That matches where developer workflows are going. A real team may use Claude Code for one task, Codex for another, Cursor for IDE edits, Gemini CLI for cheap research, and custom MCP tools for internal systems. If each agent maintains a separate memory silo, you get duplicated context, conflicting facts, and no central deletion story. A shared memory layer could become the place where agents coordinate: - previous session summaries - accepted workflow rules - failed approaches - recurring file paths - deploy receipts - known flaky tests - user-approved preferences But it only works if the memory layer is governed. Cross-agent memory multiplies value and blast radius at the same time. That is the tradeoff to evaluate, not just the star count. ## How I Would Evaluate It Before installing any persistent memory layer across a team, I would run a small harness. Create five realistic repo tasks: 1. A bug fix where the agent must remember a prior failed approach. 2. A feature where a repo convention matters. 3. A migration where an old convention becomes false. 4. A security-sensitive task where private details must not be recalled broadly. 5. A cleanup task where a memory should be deleted and stay deleted. Run each task cold, then run it with memory. Measure: - fewer repeated explanations - fewer irrelevant memories injected - lower token cost per successful run - higher task completion rate - fewer stale-memory mistakes - source receipts for every memory used - deletion and rollback behavior If memory improves recall but increases stale mistakes, it is not ready for broad automation. If it reduces repeated context and produces receipts you can audit, it is worth expanding. This pairs naturally with [Claude Code token observability](/blog/claude-code-token-burn-cache-observability) and [agent receipts](/blog/agent-swarms-need-receipts). Memory without cost and provenance telemetry is just another hidden dependency. ## The Practical Take Persistent memory is going to become standard in coding agents. Not because it is flashy. Because stateless agents waste human attention. They force developers to repeat architecture, preferences, failures, and operating rules that should compound. But the winning memory systems will not be the ones that simply retrieve the most facts. They will be the ones that make memory governable: - explicit enough to inspect - scoped enough to avoid cross-project leakage - fresh enough to survive migrations - reversible enough to undo bad learnings - measured enough to prove it helps The agent that remembers everything is not the goal. The agent that remembers what still deserves trust is. ## FAQ ### What is agent memory? Agent memory is persistent state that helps an AI agent carry useful context across turns, sessions, or tasks. For coding agents, this can include repo conventions, previous debugging attempts, user preferences, session summaries, and reusable procedures. ### Is persistent memory better than a larger context window? Not by itself. A larger context window lets the model read more at once. Persistent memory decides what should be carried forward across sessions. Good systems use both, plus context reduction so raw logs and tool output do not flood the prompt. ### Should agent memory live in a vector database? Sometimes. Vector search is useful for semantic recall, but durable coding rules often belong in explicit files, skills, manifests, or structured records with source links. The safest systems combine searchable memory with readable, reviewable artifacts. ### What is the biggest risk with coding-agent memory? Stale or over-scoped recall. A true memory can become wrong after a migration, or a rule from one repo can leak into another. That is why scope, timestamps, provenance, expiration, deletion, and rollback matter. ### How should teams evaluate memory tools? Use real repo tasks and measure repeated-context reduction, task completion, token cost, stale-memory failures, source receipts, and deletion behavior. Do not rely only on retrieval benchmarks. ## Sources - GitHub Trending: [today's trending repositories](https://github.com/trending) - GitHub: [`rohitg00/agentmemory`](https://github.com/rohitg00/agentmemory) - Letta Docs: [Agent memory and architecture](https://docs.letta.com/guides/agents/architectures/memgpt) - Letta Docs: [Memory overview](https://docs.letta.com/guides/agents/memory) - LangChain Docs: [Memory overview](https://docs.langchain.com/oss/python/concepts/memory) - LangChain Docs: [Deep agents long-term memory](https://docs.langchain.com/oss/python/deepagents/long-term-memory) - arXiv: [STALE: Can LLM Agents Know When Their Memories Are No Longer Valid?](https://arxiv.org/abs/2605.06527) - arXiv: [Memory for Autonomous LLM Agents: Mechanisms, Evaluation, and Emerging Frontiers](https://arxiv.org/abs/2603.07670)

Claude Platform on AWS Is Enterprise Agent Plumbing, Not Just Procurement

Developers Digest — Tue, 12 May 2026 00:00:00 GMT

Anthropic's Claude Platform on AWS announcement looks like a procurement story at first glance: AWS customers can access Claude platform features with AWS authentication, billing, and commitment retirement. That framing undersells it. For engineering leaders, this is about where agent adoption actually gets unblocked. Most teams do not fail to adopt AI coding agents because nobody can write a prompt. They fail because the platform questions pile up: - Who owns identity? - Which budget pays for the runs? - Can usage retire an existing cloud commitment? - Where do logs and access controls live? - Can security review the integration without another vendor path? - Can developers use the same models across experimentation and production? That is why this announcement belongs next to [Claude Managed Agents as backend job runtime](/blog/claude-managed-agents-backend-job-runtime), [Claude Code vs Codex App](/blog/claude-code-vs-codex-app-2026), and [OpenAI vs Anthropic developer experience](/blog/openai-vs-anthropic-2026). The battleground is no longer only model quality. It is the operational path from first prototype to approved platform. ## The Real Product Is Approval Surface Area Every serious AI tool has two products: 1. the thing developers touch; 2. the thing the company can approve. Developers see Claude Code, API calls, agents, and model quality. Platform teams see authentication, billing, data controls, audit, support paths, vendor risk, and existing cloud contracts. Claude Platform on AWS is aimed at the second product. It says: use the Claude platform through infrastructure your company may already have approved. That matters because a lot of AI adoption dies in the gap between "this works in a local demo" and "this can run inside our enterprise constraints." ## Why AWS Billing Is a Developer Feature Billing sounds boring until it changes behavior. If Claude platform usage can flow through AWS billing and commitment retirement, the buying motion changes. A team that could not get a separate AI vendor budget may be able to route usage through an existing cloud relationship. A platform team that already reports AWS spend can put AI agent usage beside compute, storage, and data costs. That makes [agent FinOps](/blog/400-dollar-overnight-bill-agent-finops) less theoretical. The useful question becomes: ```txt Which product team, repo, environment, and workflow burned these tokens? ``` Not: ```txt Who has the shared API key? ``` Enterprise agent adoption needs that shift. Agents will not stay small. They will run code review, migration tasks, test generation, incident summaries, docs refreshes, and background maintenance loops. The spend has to become attributable. ## Identity Is the Other Half Authentication is not just login polish. It defines what an agent can touch. When agent platforms integrate with an enterprise cloud identity path, companies can ask sharper questions: - Which teams can create agent environments? - Which roles can access production context? - Which workloads can call which models? - Which usage belongs to experimentation vs approved production? - Which logs are visible to security and platform owners? This is the same reason [Codex cloud internet controls](/blog/openai-codex-cloud-security-playbook-2026) matter. The moment an agent can read code, call tools, or run tasks in a company environment, identity becomes part of the product. ## Opposing View: This Is Just Channel Strategy There is a cynical read: this is just Anthropic making Claude easier to buy through AWS. That is partly true. Distribution matters. Cloud marketplaces and billing relationships are sales infrastructure. But for developer platforms, distribution is architecture. A model that can be bought, governed, and monitored through existing enterprise systems is more likely to become part of production workflows. A model that requires a one-off contract, a separate admin layer, and manual usage reconciliation stays in the experimentation bucket longer. So yes, this is channel strategy. It is also product strategy. ## What This Means for Agent Builders If you are building internal agent systems, take the hint. Enterprise buyers will ask for: - cloud-native identity integration; - project-level spend attribution; - environment-level policy; - model routing controls; - audit logs; - data retention settings; - support for existing procurement and commitment structures; - clean separation between experimentation and production use. The agent runtime matters, but the wrapper around the runtime determines whether it can scale inside a company. That is why [terminal agents as runtime surfaces](/blog/terminal-agents-portable-runtime-surface) are only one side of the story. The other side is platform plumbing. ## What Developers Should Watch For individual developers, the near-term benefit is not "AWS is involved." It is that enterprise AI workflows may get less fragmented. Watch for these practical changes: - fewer separate vendor approvals for Claude-based tools; - more company-approved Claude Code and API environments; - cleaner budget tags for agent runs; - stronger admin controls around model access; - more teams standardizing on approved agent workflows instead of shadow tools. This could make Claude easier to use in serious company contexts, especially where AWS is already the center of gravity. ## The Bigger Pattern OpenAI, Anthropic, GitHub, AWS, Google, and Microsoft are all converging on the same truth: agent adoption is a platform problem. The winning setup will not be "one model endpoint and a clever prompt." It will look like: - identity; - policy; - runtime isolation; - spend controls; - audit trails; - model choice; - environment routing; - human escalation; - deployment verification. That is why the [Claude Code token burn observability](/blog/claude-code-token-burn-cache-observability) conversation and the enterprise-platform conversation are connected. You cannot responsibly scale agent usage if you cannot govern it. ## The Takeaway Claude Platform on AWS is not exciting because it adds another way to buy Claude. It is exciting because it moves AI agent adoption into the systems enterprises already use to approve software. That is the quiet bottleneck. The teams that win with agents will not only pick the best model. They will build a platform where agents have identity, budgets, boundaries, receipts, and a path to production. Claude on AWS is one more sign that the category is growing up. ## FAQ ### What is Claude Platform on AWS? Anthropic describes it as a way for AWS customers to access Claude platform features using AWS authentication, billing, and commitment retirement. It is generally available as of the May 2026 announcement. ### Why does this matter for developers? It can make Claude-based tools easier to approve, budget, and govern inside companies that already operate through AWS. That matters for production agent workflows because identity, spend attribution, and policy controls become part of the adoption path. ### Does this replace Claude Code? No. Claude Code remains a developer-facing coding agent. Claude Platform on AWS is more about enterprise access and platform integration around Claude capabilities. Sources: [Anthropic: Introducing the Claude Platform on AWS](https://claude.com/blog/claude-platform-on-aws), [Hacker News discussion](https://news.ycombinator.com/item?id=48103042), [AWS Marketplace documentation](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-iam-users-groups-policies.html), [Anthropic Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview), [Anthropic Claude API documentation](https://docs.anthropic.com/en/api/overview).

Interaction Models Are the Next AI Developer Tool Interface

Developers Digest — Tue, 12 May 2026 00:00:00 GMT

Thinking Machines' post on interaction models is one of the more useful AI interface pieces to land this week because it names a problem every developer-tool team is running into: chat is not the final shape. Turn-based chat is great for asking a question. It is awkward for shared work. Coding agents already proved that. A serious agent session is not one prompt and one answer. It is a loop of reading files, asking clarifying questions, editing code, running tests, showing diffs, getting corrected, opening browser checks, and leaving a receipt. That is why [terminal agents are becoming runtime surfaces](/blog/terminal-agents-portable-runtime-surface), why [Codex loops](/blog/codex-loops-boris-cherny-agent-routines) matter, and why [long-running agent harnesses](/blog/long-running-agents-need-harnesses) keep showing up. The next interface layer is not "better chat." It is better coordination. ## What Interaction Models Mean Thinking Machines describes interaction models as systems that handle multimodal, real-time collaboration across audio, video, and text. The important idea is not merely multimodality. The important idea is that the model participates in an ongoing interaction instead of waiting for a fully packaged prompt. For developer tools, that maps cleanly to the work we already do: - watch a test fail; - inspect a diff; - hear a spoken constraint; - see a screenshot; - follow a cursor; - notice a console error; - ask whether to continue; - remember which file is the current focus; - hand control back to the human at the right moment. That is a different product shape from a chat box glued beside an editor. ## Why Chat Feels Wrong for Coding Agents Chat forces developers to serialize messy work into text. You have to explain: - which file matters; - what changed; - which visual bug you mean; - which test output is relevant; - which instruction still applies; - which previous decision should be ignored. A good coding agent can infer some of that from the repo, but the interface still makes the human do too much packaging. This is why tools keep adding richer surfaces: IDE diffs, terminal execution, browser screenshots, task plans, subagents, worktrees, PR comments, and persisted instructions. They are not decorations. They are attempts to escape the limitations of pure chat. ## The Developer Tool Version In developer tools, an interaction model should treat the repo, terminal, browser, issue tracker, and human as parts of one workspace. Imagine a coding agent interface where: - the agent can see the current failing test and the diff beside it; - your spoken correction is attached to the exact UI state; - the browser screenshot becomes part of the task context; - the agent knows whether it is in exploration, implementation, review, or deploy verification mode; - every action lands in a receipt that another agent can resume. That is not science fiction. Pieces of it already exist across [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Codex, Cursor, Zed, GitHub Copilot, and browser automation workflows. The problem is that the pieces are still fragmented. ## Opposing View: Chat Is Enough There is a fair counterargument: chat is simple, universal, and composable. A text box can drive anything. Developers already understand it. APIs are easier. Logs are easier. Automation is easier. I agree with the first half. Chat should not disappear. But chat should become one control among many, not the whole interface. The same way command lines did not disappear when IDEs improved, text prompts will remain useful. They just should not be responsible for carrying every bit of state. The best developer tools will support text, but they will not force every interaction through text. ## The Missing Primitive Is Shared State The real prize is shared state. Developer work has a lot of state: - files; - diffs; - test results; - logs; - browser screenshots; - issue comments; - design constraints; - deploy status; - previous agent attempts; - budget and time limits. Chat transcripts are a poor database for that. They are verbose, ambiguous, and hard to resume. A better interaction model should store task state explicitly. That is why [agent context reduction](/blog/agent-context-reduction-pattern) matters. The goal is not to stuff more transcript into a context window. The goal is to keep the right state in the right structure. ## What To Build Now If you are building AI developer tools, do not wait for a perfect multimodal model to improve the interface. Start with the interaction contract. Add these primitives: - **Mode**: exploration, implementation, review, verification, deploy. - **Current artifact**: file, PR, route, screenshot, test, issue. - **Authority level**: read-only, edit, command execution, merge, deploy. - **Evidence**: tests run, screenshots captured, source links checked. - **Resume state**: what another agent needs to continue without replaying the whole chat. - **Escalation rule**: when the agent must stop and ask. Those primitives make any model better because they reduce ambiguity. ## Why This Matters for Content and SEO Too The same idea applies outside code. A content automation should not only say "write a post." It should know: - the trend source; - the existing posts to avoid duplicating; - the internal links to include; - the image style; - the checks to run; - the deployment verification step; - the next self-improvement note. That is exactly the loop behind [skills as agent operating systems](/blog/skills-are-the-new-agent-operating-system). A skill is a tiny interaction model: state, constraints, tools, and expected output. ## The Takeaway Interaction models are a useful frame because they push AI tools beyond prompt-response thinking. For developer tools, the future interface is a shared workspace where the model can coordinate across code, tests, browser state, voice, screenshots, issues, and deployment receipts. Chat will still be there. It just will not be the whole product. The best agent tools will feel less like asking a chatbot to code and more like working inside a system that understands the work in progress. ## FAQ ### What is an interaction model in AI? An interaction model is a system design for how a model collaborates with users across time, modalities, and shared state. Instead of treating every request as a standalone chat turn, it handles ongoing work. ### Why does this matter for AI coding tools? Coding work involves files, diffs, tests, terminals, screenshots, issue trackers, and deployment checks. A chat-only interface makes developers compress all of that state into text, which is inefficient and error-prone. ### Does this mean chat interfaces are going away? No. Text prompts remain useful. The shift is that chat becomes one input inside a richer workspace, not the entire interface. Sources: [Thinking Machines: Interaction Models](https://thinkingmachines.ai/blog/interaction-models/), [Hacker News discussion](https://news.ycombinator.com/item?id=48100524), [Anthropic Claude Code overview](https://docs.anthropic.com/en/docs/claude-code/overview), [OpenAI Codex documentation](https://developers.openai.com/codex/), [W3C Multimodal Interaction Architecture](https://www.w3.org/TR/mmi-arch/).

TanStack's npm Compromise Is the CI Lesson Agent Teams Needed

Developers Digest — Tue, 12 May 2026 00:00:00 GMT

TanStack's May 11 npm postmortem is the kind of incident AI-heavy engineering teams should read slowly. The headline was a serious supply-chain compromise: malicious versions were published across dozens of `@tanstack/*` packages after an attacker chained GitHub Actions behavior, cache poisoning, and OIDC token extraction. The durable lesson is broader than TanStack. If you are letting agents open pull requests, edit workflow files, run CI, or prepare releases, your agent program is now coupled to your CI trust model. That is the same operational theme behind [prompt injection in open source](/blog/prompt-injection-open-source), [agent receipts](/blog/agent-receipts-ai-coding), and [long-running agent harnesses](/blog/long-running-agents-need-harnesses). Agent output is not safe because the diff looks small. It is safe when the workflow around the diff has the right boundaries. ## What Happened TanStack says the attacker chained three important primitives: - a `pull_request_target` workflow path that crossed the fork and base-repository trust boundary; - GitHub Actions cache poisoning across that boundary; - OIDC token extraction from runner memory, which enabled npm publishing. The exact details matter, but the pattern matters more: a CI workflow treated untrusted pull request context as if it could safely influence trusted release machinery. That is the part agent teams should underline. Agents do not invent new categories of infrastructure risk every time. They amplify the old ones by increasing the number of PRs, workflow edits, dependency updates, and release-adjacent tasks moving through the system. ## Why This Hits Agent Workflows Differently Classic CI security assumes human developers are the primary authors of risky changes. AI coding agents change the volume and shape of that work. A team that runs [Codex loops](/blog/codex-loops-boris-cherny-agent-routines), [Claude Code subagents](/blog/claude-code-agent-teams-subagents-2026), or GitHub-hosted coding agents will naturally delegate chores like: - dependency refreshes; - test fixture updates; - workflow cleanups; - release note generation; - package publishing checks; - flaky CI repair. Those tasks feel boring, which is exactly why they get delegated. But boring does not mean low privilege. A one-line workflow change can matter more than a 2,000-line application diff. The dangerous failure mode is not "the agent wrote bad TypeScript." It is "the agent made a plausible CI change that lets untrusted code reach a trusted credential boundary." ## The Real Boundary Is Not Human vs AI The easy take is to say "do not let AI touch CI." That is too blunt. The better boundary is trusted vs untrusted execution. A human can make the same mistake. An agent can make the same mistake faster. The fix is to design the release system so neither can accidentally turn a fork PR into a credentialed publish path. For agent teams, that means release automation should be split into layers: 1. **Untrusted validation**: test the proposed change without secrets and without publish rights. 2. **Reviewable artifact creation**: build packages, diffs, previews, and SBOMs as artifacts. 3. **Trusted promotion**: publish only from protected branches, protected environments, or manually approved release jobs. 4. **Receipt capture**: record exactly which commit, workflow, token audience, package version, and actor performed the release. That last point is where agent operations and security converge. A good [agent FinOps](/blog/400-dollar-overnight-bill-agent-finops) system tells you what the agent spent. A good agent security system tells you what authority the agent touched. ## `pull_request_target` Needs a Higher Bar `pull_request_target` exists for real reasons. It can run with base-repository context, which is useful for labels, comments, and some automation around external contributions. But any workflow that combines `pull_request_target`, untrusted checkout behavior, caches, generated scripts, install steps, or release credentials deserves a hard review. This is not an agent-specific rule. It is a GitHub Actions trust-boundary rule. Agent teams should make it explicit: - agents may comment on external PRs; - agents may summarize CI and review state; - agents may propose workflow changes in a normal PR; - agents may not create or modify credentialed publish paths without human review; - agents may not merge changes that alter release credentials, OIDC audiences, package permissions, or protected environment rules. That sounds bureaucratic until you compare it with the blast radius of a compromised package. ## The Agent Review Checklist Should Include CI Authority Most AI code review checklists focus on code quality: - Does it compile? - Are tests passing? - Is the implementation too broad? - Did the agent delete something important? After this incident, agent review needs an authority section too. Ask these questions for every agent-authored PR that touches CI, dependencies, package publishing, install scripts, or repository settings: - Does this change alter when secrets are available? - Does it run untrusted code before a credentialed step? - Does it restore caches across trust boundaries? - Does it make package publishing easier without adding an approval gate? - Does it change token permissions from read to write? - Does it add dynamic script execution in a privileged job? - Does it rely on labels, branch names, or filenames as a security control? This is the same discipline as [agent bugs moving up the stack](/blog/overnight-agents-workflow). The bug is often not a bad line of code. It is a bad operating assumption. ## Opposing View: This Is Just CI Security The opposing take is reasonable: TanStack's postmortem is about GitHub Actions and npm publishing, not AI agents. You do not need to mention agents to understand the vulnerability class. That is true. The root cause lives in CI and release engineering. But AI changes the exposure surface. More teams are now asking agents to maintain the exact files that define CI trust boundaries. More teams are also running background loops that wake up, inspect GitHub state, and push small changes without the same attention a senior engineer would give a release workflow. So the agent angle is not "AI caused this." The agent angle is "agent adoption makes this category of mistake easier to repeat at scale." ## The Practical Policy Here is the policy I would put into an agent runbook: ```txt Agents may propose CI and release changes. Agents may not merge or execute credential-affecting CI changes. Any change touching package publishing, OIDC, secrets, environments, workflow permissions, caches, or pull_request_target requires human review. Trusted publish jobs must run from protected branches or protected environments only. Every release job must emit a receipt: commit, package, version, workflow, actor, token audience, and artifact hash. ``` That is not anti-agent. It is how you make agents boring enough to use. ## What To Measure Next If your team is already running coding agents, track these metrics: - agent-authored PRs that touch `.github/workflows`; - agent-authored dependency and lockfile PRs; - workflows that use `pull_request_target`; - workflows with `id-token: write`; - publish jobs without protected environment approval; - release jobs that consume caches built from untrusted PR context; - mean time from package publish to rollback. Those numbers will tell you whether your agent system is increasing release risk or just increasing normal application throughput. ## The Takeaway TanStack's incident should not make teams stop using agents. It should make teams stop treating CI as background plumbing. AI agents inherit your trust boundaries. If those boundaries are fuzzy, agents will make the fuzziness visible. If the boundaries are explicit, agents can work inside them productively. The next mature agent platform will not only generate code. It will understand workflow authority, ask for escalation before touching release paths, and leave receipts that make supply-chain review boring. That is where this category has to go. ## FAQ ### Was the TanStack incident caused by AI? No. TanStack's public postmortem describes a GitHub Actions and npm supply-chain compromise. The AI lesson is that coding-agent workflows often touch the same CI and release files, so teams need stronger trust-boundary policies before delegating those chores. ### Should agents be banned from editing CI files? Not completely. Agents can propose CI changes, summarize workflows, and open reviewable PRs. They should not merge or execute changes that affect secrets, OIDC, package publishing, protected environments, or trusted release jobs without human approval. ### What is the safest first agent security control? Start by blocking autonomous changes to `.github/workflows`, package publishing configuration, and repository secrets. Then add a review checklist for credential boundaries, cache behavior, OIDC token use, and protected environment rules. Sources: [TanStack npm supply-chain compromise postmortem](https://tanstack.com/blog/npm-supply-chain-compromise-postmortem), [Hacker News discussion](https://news.ycombinator.com/item?id=48100706), [GitHub Actions `pull_request_target` documentation](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request_target), [GitHub Actions OIDC hardening guide](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect), [npm package provenance documentation](https://docs.npmjs.com/generating-provenance-statements).

Codebase Graphs Are the New Agent Map

Developers Digest — Sun, 10 May 2026 00:00:00 GMT

The most useful GitHub trend this morning is not another chat wrapper. It is a map. [Graphify](https://github.com/safishamsi/graphify) is a fast-growing Claude Code skill that turns a folder of code, markdown, PDFs, screenshots, diagrams, schemas, and other project material into a queryable knowledge graph. The pitch is specific: drop it on a repo or research folder, get an interactive graph, an Obsidian-style vault, a wiki, a JSON graph, a report of high-degree nodes, surprising connections, suggested questions, and provenance labels for what was extracted versus inferred. That is a much more interesting signal than the star count alone. The agent market has spent the last year arguing about which model writes the best patch. The next bottleneck is different: agents need durable maps of the systems they are operating inside. Without that, every long coding run becomes another expensive rediscovery loop. That is the same pressure behind [terminal agents becoming portable runtime surfaces](/blog/terminal-agents-portable-runtime-surface), [Claude Code token-burn observability](/blog/claude-code-token-burn-cache-observability), and [the context reduction pattern](/blog/agent-context-reduction-pattern). The agent does not need every file pasted into context. It needs the right local map, with evidence, boundaries, and a path back to verification. ## The Take Codebase graphs are becoming the new repo map. Aider made the repo-map idea concrete for AI coding: use tree-sitter to build a compact view of symbols and relationships, then spend context on the parts of the codebase that matter. That pattern still works, and it is why [Aider vs Claude Code](/blog/aider-vs-claude-code) is still a useful comparison. Graphify points at the next version of the same idea. Modern agent work is not only source code. It includes: - product notes - schemas - migration history - screenshots - architecture diagrams - bug reports - transcripts - research papers - design system rules - deployment runbooks - prior agent decisions Those objects do not fit neatly into a file tree. They fit better as a graph. If the agent can ask "what connects this billing route to this auth policy?" or "which docs contradict the current schema?" or "what changed since the last successful deploy?", it can navigate like an engineer instead of rereading the whole repo like a distracted intern. ## Why This Is Trending Now The timing makes sense. Coding agents have become capable enough that the failure mode moved up a layer. The model can usually make a plausible edit. The hard part is knowing which edit is appropriate inside this specific system. That is why developers keep building surrounding infrastructure: - skills and memory files to preserve local conventions - repo maps to compress code structure - MCP servers to expose tool state - terminal runtimes with approvals and rollback - hooks that run tests after edits - cost monitors that catch runaway context - PR receipts that explain what changed and why Graphify sits in that same category. It is not trying to be the model. It is trying to be part of the agent's working memory. The README claims a 71.5x token reduction on a mixed corpus of Karpathy repos, papers, and images. Treat that as a project-specific benchmark, not a universal law. But the direction is right: structure beats repeated full-context reads when the corpus gets large enough. ## The Real Product Is Provenance The best detail in Graphify is not the visual graph. It is the edge labeling. The project says each edge is tagged as `EXTRACTED`, `INFERRED`, or `AMBIGUOUS`. That matters because agent context is dangerous when it looks more certain than it is. A useful codebase map should separate: - facts found directly in code - relationships inferred from names or call paths - claims copied from docs - stale notes that may no longer match production - hypotheses that need verification That distinction is the difference between a map and fan fiction. This is also where many memory systems fall apart. A persistent note that says "the checkout flow uses Stripe webhooks" is not enough. The agent needs to know where that came from, when it was observed, which files support it, and which tests or logs can prove it still holds. That is why the next useful agent-memory product will look less like a notebook and more like a graph with receipts. ## The Opposing Take The skeptical view is fair: knowledge graphs have been oversold before. Developers have seen enterprise graph demos where everything connects to everything, the visualization looks impressive, and the daily workflow never changes. A codebase graph can become another artifact that ages out of sync, costs tokens to maintain, and gives the agent a false sense of understanding. There are real failure modes: - The graph can preserve stale architecture decisions after the code moved on. - Inferred edges can look factual if the UI does not mark uncertainty clearly. - Generated wiki pages can compress away the edge case that matters. - Multimodal extraction can misread screenshots or diagrams. - A graph can help exploration but still fail to validate behavior. - Rebuild hooks can add noise if every commit produces a large artifact churn. So the right question is not "does the graph look clever?" The right question is "does this graph reduce real agent mistakes?" If it does not help the agent choose better files, avoid duplicate work, explain risk, run better tests, or leave better receipts, it is decoration. ## What A Serious Codebase Graph Needs For agent work, a codebase graph should be scored like infrastructure. ### 1. Incremental Updates The graph has to stay current without turning every edit into a full re-index. Graphify's cache and `--update` path are the right shape. Code changes should be cheap to refresh. Docs, diagrams, and PDFs can take a slower pass. The important part is that the agent knows whether it is reading a fresh edge or stale context. ### 2. Source Links Every useful node should route back to evidence. If a graph says a route depends on a policy, click through to the route, policy, migration, test, or doc. If the relationship came from inference, say that. If it came from a generated summary, point to the raw source. This is the same standard public technical content should meet: claims need sources. Agents should hold themselves to the same rule. ### 3. Agent-Navigable Output The visual graph is useful for humans, but agents need boring files. Graphify's wiki output is interesting because it gives another agent a markdown entry point. That is the practical surface. A coding agent can read `index.md`, follow links, inspect a community page, and then jump to files. It does not need to parse a dense PNG of nodes. ### 4. Uncertainty Labels The graph should make uncertainty loud. `EXTRACTED`, `INFERRED`, and `AMBIGUOUS` are good starting labels. Teams may need more: `STALE`, `TESTED`, `PRODUCTION_OBSERVED`, `DOC_ONLY`, `HUMAN_CONFIRMED`, or `BROKEN_BY_RECENT_DIFF`. This is where graph memory connects to [agent swarms needing receipts](/blog/agent-swarms-need-receipts). More context is not better unless the context explains how much to trust it. ### 5. Verification Paths A graph should not end at an answer. It should end at a check. If the agent asks "what owns this checkout failure?", the graph can identify likely files and docs. The next step should be a test, log query, smoke check, or reproduction command. That is how codebase maps become operational, not ornamental. This is the same lesson behind [long-running agents needing harnesses](/blog/long-running-agents-need-harnesses). A map is useful because it points the harness at the right verification loop. ## Where This Fits In The Stack I would not replace existing tools with a graph layer. I would add it where current agent workflows already leak time. Use a codebase graph when: - the repo is too large for normal context stuffing - architecture knowledge lives across docs, tickets, schemas, and code - multiple agents are editing related modules - onboarding requires repeated "where does this live?" questions - migrations and policies matter as much as application code - historical decisions affect current implementation choices Do not use it as a substitute for: - tests - typechecks - code review - runtime logs - source-level inspection - explicit task acceptance criteria The graph should narrow the search space. It should not become the authority. ## My Take Graphify is interesting because it names a real pain: agents are still bad at carrying system structure across sessions. That does not mean every team needs a knowledge graph tomorrow. Small repos still fit in simple context windows. Many projects need better tests before they need better maps. And any generated graph has to prove that it reduces mistakes, not just tokens. But the direction is right. AI coding is moving from prompt craft to operating systems. Repos need maps. Agents need provenance. Teams need receipts. The winning context layer will not be the one that remembers the most. It will be the one that helps an agent decide what to inspect, what to trust, and what to verify next. Sources: [Graphify on GitHub](https://github.com/safishamsi/graphify), [Aider repo map documentation](https://aider.chat/docs/repomap.html), [Sourcegraph Cody docs](https://sourcegraph.com/docs/cody), [Model Context Protocol introduction](https://modelcontextprotocol.io/introduction), [Claude Code memory docs](https://docs.anthropic.com/en/docs/claude-code/memory). ## FAQ ### What is Graphify? Graphify is a Claude Code skill and CLI workflow that turns folders of code, docs, PDFs, images, diagrams, and other project material into a queryable knowledge graph. It can output an interactive graph, markdown wiki, Obsidian-style vault, JSON graph, and report. ### Why do AI coding agents need codebase graphs? Agents need compact structure. A graph can show relationships among files, functions, docs, schemas, decisions, and tests without stuffing the whole repo into context. That helps the agent choose better files and ask better follow-up questions. ### Is a codebase graph better than a repo map? It depends on the job. A repo map is excellent for symbol-level code navigation. A broader graph is more useful when the task crosses code, documentation, diagrams, research, schemas, and prior decisions. The best systems will likely use both. ### What is the risk of using generated knowledge graphs? The main risk is false confidence. If inferred or stale relationships look factual, the agent may make wrong edits faster. A serious graph needs source links, uncertainty labels, freshness metadata, and verification paths. ### Should every repo add a codebase graph? No. Small repos may not need it. Add a graph when repeated context discovery is slowing agents down, when knowledge lives across many artifact types, or when multiple agents need a shared map of the same system.

Claude Managed Agents Are Starting to Look Like Backend Jobs

Developers Digest — Sat, 09 May 2026 00:00:00 GMT

Anthropic's latest Claude Managed Agents update looks like an agent feature launch on the surface: multiagent sessions, outcomes, dreaming, vault refresh, and webhooks. The more useful read is that managed agents are turning into a backend job runtime. That is the angle developers should care about. Once an agent can run for a while, split work across specialized threads, refresh credentials, emit webhooks, ask for permission, and prove an outcome, it stops behaving like a chat tab. It starts behaving like a long-running production process. That puts Claude Managed Agents in the same operational lane as [Codex goals and Claude managed outcomes](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences), [terminal agents as portable runtime surfaces](/blog/terminal-agents-portable-runtime-surface), and [long-running agent harnesses](/blog/long-running-agents-need-harnesses). The winning teams will not just prompt these systems better. They will wrap them like jobs: queued, idempotent, observable, interruptible, budgeted, and auditable. ## What Changed Anthropic's announcement says managed agents now include multiagent orchestration, outcomes, dreaming, vault refresh, and webhooks ([Anthropic announcement](https://claude.com/blog/new-in-claude-managed-agents)). The docs make the shift clearer. [Multiagent sessions](https://platform.claude.com/docs/en/managed-agents/multi-agent) let a coordinator agent delegate to other agents inside a single session. Those agents share a container and filesystem, but each runs in its own context-isolated session thread with its own conversation history. The coordinator sees condensed activity on the primary event stream, while operators can inspect individual session threads when needed. [Outcomes](https://platform.claude.com/docs/en/managed-agents/define-outcomes) turn "done" into a rubric-driven evaluation loop. Instead of trusting that an agent stopped at the right time, you define success criteria and inspect whether the outcome was satisfied, needs revision, hit max iterations, or failed. [Webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks) notify your system about state changes such as sessions starting, idling, rescheduling, terminating, creating threads, or finishing outcome evaluation. The webhook docs also say payloads include the event type and resource ID, then your app fetches the fresh object by ID. That last detail matters. It is exactly how serious backend systems avoid stale event payloads, duplicate delivery bugs, and polling loops. ## The Take The agent platform race is moving from "can the model use tools?" to "can the run be operated like infrastructure?" A production agent run needs the same boring properties as a background job: - a durable job identifier - explicit status transitions - retry semantics - duplicate delivery handling - permission checkpoints - logs and event streams - typed completion states - budget limits - a way to wake humans up only when needed Claude Managed Agents is not the only path there. You can build this around Codex, Claude Code, GitHub Actions, a queue, or your own harness. But Anthropic's managed-agent surface is a strong signal about where the category is going. Agent execution is becoming backend execution. ## Webhooks Change the Integration Shape Without webhooks, a managed agent is something your app starts and then checks later. With webhooks, it becomes something your app can subscribe to. That difference changes the architecture. Your application can now react when an agent idles for a permission approval, when a multiagent thread is created, when a transient error triggers a reschedule, or when an outcome evaluation finishes. That is the same reason [agent-native backends](/blog/agent-native-backends-insforge) are interesting. The valuable surface is not just the model. It is the control plane around the run. The webhook docs also include the important production caveats: - event payloads are small and require a follow-up fetch - duplicate deliveries can happen - ordering is not guaranteed - non-2xx responses trigger retry behavior - endpoints can be disabled after repeated delivery failures Those are normal webhook rules, but they are easy to forget when the product category is called "agents." If you wire this like a toy chat callback, it will break like a toy chat callback. The right shape is boring: 1. Verify the signature. 2. Deduplicate by event ID. 3. Fetch the current session, thread, or outcome object by ID. 4. Update your own run record transactionally. 5. Trigger the next action only from your stored state. 6. Treat ordering as a hint, not a guarantee. That is not glamorous. It is what keeps an overnight agent from waking up three people for the same stuck approval. ## Multiagent Sessions Need Handoff Discipline The multiagent docs are also more operational than they first look. The coordinator can delegate to a roster of agents. Anthropic frames the best use cases as parallelization, specialization, and escalation. That maps directly to how engineering teams already split work: researcher, implementer, reviewer, test writer, security reviewer, docs writer. But the docs include constraints that should shape your design: - all agents share the same container and filesystem - each agent has isolated thread context - tools and context are not shared - the coordinator can delegate only one level deep - the roster can include up to 20 unique agents - session status aggregates thread activity - permission requests from worker threads are cross-posted to the primary thread Those details create a useful boundary. Do not treat multiagent sessions as a magic swarm. Treat them as a supervised job with worker threads. Each worker needs a narrow assignment, a completion artifact, and a reason to exist. If your coordinator delegates "improve the codebase" to five agents, you just made five vague agents. If it delegates "review auth policy changes," "write regression tests," and "summarize docs changes," you have an actual workflow. This is the same practical lesson behind [parallel coding agents needing merge discipline](/blog/parallel-coding-agents-merge-discipline). Parallelism is only useful when the handoffs are crisp enough to merge. ## Outcomes Are the Stop Condition The most important primitive is still outcomes. Tools let the agent act. Multiagent sessions let it split work. Webhooks let your app react. But outcomes define when the run is allowed to stop. That is why the existing [Codex `/goal` vs Claude outcomes comparison](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences) still matters. A durable loop is not the same thing as a good stopping rule. "Keep going" and "prove it is done" are different product primitives. For production workflows, outcomes should be written like acceptance criteria: - what files or artifacts must exist - what tests or checks must pass - what source evidence must be cited - what risk review must be completed - what business constraint must remain true - what human handoff note must be left behind The anti-pattern is using an outcome as a vibe check. Bad outcome: "Make the report good." Better outcome: "The report cites three primary sources, lists assumptions, includes a recommendation table, flags unknowns, and has no unsupported pricing claims." This matters even more as agents start coordinating with other agents. The coordinator can produce a polished summary while a worker missed the actual requirement. Outcomes force the final handoff to be judged against a rubric instead of the coordinator's confidence. ## The Opposing Take There is a fair skeptical response: isn't this just queue infrastructure with a model attached? In many ways, yes. That is the point. Teams already know how to run jobs, retries, event handlers, dashboards, queues, alerts, and approval workflows. The mistake would be treating agents as a brand-new metaphysical category that needs brand-new operational instincts. The harder skeptical question is whether managed-agent platforms hide too much. If the provider owns the session runtime, filesystem, thread orchestration, credential vault, and outcome evaluation loop, you get speed but lose some control. You need to understand what can be exported, logged, replayed, interrupted, and governed from your side. For some teams, a self-hosted harness around Claude Code, Codex, or an open-source agent runtime will be the better answer. For others, a managed runtime is exactly the right tradeoff because the provider handles the painful execution substrate. The decision should not be ideological. Ask what failure evidence you get back. ## The Production Checklist Before treating managed agents as production infrastructure, I would require: - a local run record for every agent session - webhook signature verification - idempotent event handling - duplicate event detection - explicit state machine transitions - max runtime and max spend caps - per-tool permission policy - outcome rubrics stored in version control - thread-level logs or summaries for worker agents - human escalation rules for idled sessions - a receipt artifact after completion - a rollback or replay plan for failed runs This is also where [managed-agent FinOps](/blog/400-dollar-overnight-bill-agent-finops) becomes unavoidable. A long-running agent that can reschedule, fan out, call tools, and revise toward an outcome can produce serious value. It can also burn money in a loop if you do not cap it. ## A Concrete Architecture If I were adding Claude Managed Agents to a developer platform today, I would not start with a chat UI. I would start with a job table: ```txt agent_runs id provider_session_id status objective outcome_rubric_version max_runtime_minutes max_budget_usd created_by created_at updated_at completed_at agent_events id provider_event_id run_id event_type provider_resource_id received_at processed_at ``` Then I would wire webhooks into that table, not directly into business actions. The webhook handler should only authenticate, dedupe, fetch current state, and store the event. A separate worker should decide whether to notify a human, resume a session, fetch a thread transcript, or mark the run complete. That extra hop is what lets you debug the system later. It also makes it easier to swap providers. The same run model can hold Codex automation receipts, Claude Managed Agent sessions, or GitHub Copilot agent tasks. ## What To Watch Next The next useful features will probably sound boring: - first-class run budgets - better thread export - outcome history diffs - webhook replay tooling - built-in dead-letter queues - per-agent cost attribution - approval policies as code - portable receipts across providers Those are not flashy agent demos. They are the things that make agents safe to use every day. That is why this Anthropic update matters. It is not just another layer of agent capability. It is another step toward agents being operated like backend systems. The teams that win will not be the teams with the most dramatic autonomous demo. They will be the teams whose agents can fail quietly, resume cleanly, explain what happened, and hand off a receipt a human can trust. Sources: [Anthropic announcement](https://claude.com/blog/new-in-claude-managed-agents), [Claude Managed Agents multiagent sessions](https://platform.claude.com/docs/en/managed-agents/multi-agent), [Claude Managed Agents webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks), [Claude Managed Agents outcomes](https://platform.claude.com/docs/en/managed-agents/define-outcomes), [Claude Managed Agents launch post](https://claude.com/blog/claude-managed-agents). ## FAQ ### What are Claude Managed Agents? Claude Managed Agents are Anthropic's hosted infrastructure for running longer-lived Claude agents with managed environments, sessions, tools, files, credentials, tracing, and orchestration features. ### Why compare managed agents to backend jobs? Because production agent runs need the same mechanics as backend jobs: IDs, states, retries, webhooks, logs, budgets, approvals, and completion criteria. The model is only one part of the runtime. ### What are multiagent sessions in Claude Managed Agents? Multiagent sessions let a coordinator agent delegate work to other configured agents inside one managed session. Worker agents have isolated context threads while sharing the same container and filesystem. ### What are outcomes in Claude Managed Agents? Outcomes define what "done" means for an agent run. They use rubric-style criteria so the system can evaluate whether the output is satisfied, needs revision, reached max iterations, or failed. ### How should developers handle Claude Managed Agents webhooks? Treat them like normal production webhooks. Verify signatures, deduplicate by event ID, fetch current resource state by ID, handle retries, and never assume delivery ordering.

Agent-Native Backends Are the Next AI Coding Bottleneck

Developers Digest — Fri, 08 May 2026 00:00:00 GMT

The most interesting backend trend on GitHub this morning is not "another Supabase alternative." It is the shape of the interface. [InsForge](https://github.com/InsForge/InsForge) describes itself as an open-source backend platform for agentic coding. The pitch is direct: give coding agents database, auth, storage, compute, hosting, and an AI gateway so they can ship full-stack apps end to end. The project exposes those backend primitives through an MCP server, plus a CLI and skills path for cloud users. That matters because AI coding agents are getting weirdly good at the frontend half of software and still fragile around the backend half. A model can generate a Next.js page, wire a form, and make the UI look decent. The failure mode usually shows up one layer deeper: wrong schema assumptions, missing migrations, auth rules that look plausible but are unsafe, storage buckets with unclear policies, functions deployed without logs, or a production deploy that the agent never actually verified. That is the same operating lesson behind [terminal agents becoming portable runtime surfaces](/blog/terminal-agents-portable-runtime-surface) and [long-running agents needing harnesses](/blog/long-running-agents-need-harnesses). Once the agent can change real infrastructure, the runtime around the model matters more than the prompt. ## The Take The next backend platform category is not just backend-as-a-service. It is **backend-as-an-agent-control-plane**. That sounds like vendor language, but the distinction is practical. A normal backend platform is optimized for a human developer reading docs, clicking dashboards, writing migrations, and checking logs. An agent-native backend needs to expose the same primitives as structured operations the agent can inspect, change, verify, and report back on. InsForge is interesting because its README names those verbs: - read backend context and state - pull documentation, schemas, metadata, deployed functions, bucket contents, auth config, and runtime logs - deploy edge functions - run database migrations - create storage buckets - set up auth providers - configure backend resources directly That list is not just a feature list. It is a definition of what an agent needs to safely touch a backend. For a broader stack decision, pair this with [Convex vs Supabase for AI apps](/blog/convex-vs-supabase-ai-apps) and the [Next.js AI app stack guide](/blog/nextjs-ai-app-stack-2026). Those posts answer which backend feels good to humans. This post is about what changes when an agent is the operator. ## Why Backends Break Agents Backends punish uncertainty. Frontend code can be visually inspected. If the padding is wrong, the page looks wrong. If a component imports the wrong icon, the build usually catches it. If the agent makes a bad layout choice, you can screenshot it and iterate. Backend mistakes hide longer. A generated migration can pass locally and still fail against production data. An auth rule can satisfy the happy path while leaking a tenant boundary. A storage upload can work for the owner and fail for a collaborator. A serverless function can deploy but time out under real input. A model gateway can be wired correctly but blow through cost because nobody set a session cap. That is why [agent skills need exit criteria](/blog/agent-skills-production-checklist). "Build the backend" is too vague. The useful instruction is closer to: > Change the schema, apply the migration, update the SDK usage, verify auth behavior, inspect logs, run the route smoke test, and leave a receipt. The agent cannot do that reliably if every backend operation lives behind a dashboard built for humans. ## What Agent-Native Actually Means Agent-native does not mean "the backend has AI features." It means the backend gives the agent a constrained operating surface: ### 1. Discoverable State The agent needs to ask what exists before it edits anything. That includes schemas, tables, policies, functions, storage buckets, secrets that are present but not exposed, deploy history, logs, and environment shape. The goal is not to dump the whole system into context. The goal is to return compact, structured facts the agent can reason over. This is the backend version of [the context reduction pattern](/blog/agent-context-reduction-pattern). Keep the large state in the system. Return the summary, evidence, and next safe action. ### 2. Safe Mutations "Run arbitrary SQL" is powerful, but it is not enough. An agent-native backend should separate read-only inspection, proposed migrations, applied migrations, function deploys, auth config changes, and destructive operations. Each category should be visible in the transcript. Risky operations should be gated. The platform should make it easy to preview and roll back where possible. That is the same permission-boundary problem terminal agents are solving with approvals and sandboxing. Backends need the equivalent. ### 3. Verification Hooks Agents need a short path from "I changed it" to "I proved it works." For backend work, that means logs, health checks, migration status, endpoint tests, auth policy checks, and deployed function output need to be callable from the same surface the agent used to make the change. This is where normal BaaS dashboards fall short for automation. They are excellent for humans. They are not always excellent as machine-verifiable receipts. ### 4. Portable Primitives InsForge's primitive list is familiar: Postgres, auth, S3-compatible storage, edge functions, model gateway, compute, deployment. That familiarity is a feature. The agent should not have to learn a new database concept for every project. It should learn the team's conventions around boring primitives. The better the platform maps to known infrastructure, the easier it is to review the agent's work. ## The Opposing Take There is a fair skeptical read here: do we really need another backend platform because coding agents exist? Maybe not. Supabase, Convex, Neon, Clerk, Railway, Fly.io, Cloudflare, Vercel, and plain Docker already cover most backend needs. The best developer teams can build an agent-readable layer around those tools with CLIs, APIs, docs, migrations, and smoke tests. In many cases, that is the right answer. The risk with a new agent-native platform is abstraction drift. If the agent learns a simplified control plane but production behavior lives in the underlying database, storage system, auth provider, and deployment target, the abstraction can hide the exact details that matter during an incident. There is also a security angle. Giving an agent backend tools is not automatically safer than giving it shell access. It is only safer if permissions, logs, previews, approvals, and rollback boundaries are better than the raw tools they replace. So the bar should be high. Do not evaluate InsForge or any agent-native backend by whether the demo scaffolds an app. Evaluate whether it makes backend changes more inspectable than the tools you already use. ## The Evaluation Checklist If a backend claims to be built for agents, I would score it on these questions: - Can the agent list the current schema, functions, auth config, buckets, and deployment state without overloading context? - Can it propose a migration before applying it? - Can destructive actions require explicit approval? - Can every mutation produce a receipt with who changed what, when, and why? - Can the agent read runtime logs after a failed deploy? - Can it run a route-level smoke test after creating an endpoint? - Can it verify auth and storage policies from multiple user roles? - Can it export enough state for human review in a pull request? - Can it work locally and in production without hiding environmental differences? - Can the team bypass the agent layer and use standard Postgres, S3, functions, and deploy tooling when needed? That last question matters. The agent layer should make common work safer. It should not become the only way to understand the system. ## My Take InsForge is worth watching because it names a real bottleneck. AI coding agents are no longer blocked by generating files. They are blocked by operating systems safely: repos, browsers, CI, deployments, databases, auth, storage, logs, and cost controls. The frontend agent story is already crowded. The backend operator story is earlier and more important. Whoever makes backend state inspectable, mutations gated, and verification receipts automatic will have a real wedge. That does not mean every team should migrate to a new backend. It means every team using coding agents should ask whether their backend is legible to the agent. If the answer is no, the agent will keep guessing. And backend guesses are expensive. Sources: [InsForge GitHub repository](https://github.com/InsForge/InsForge), [InsForge docs](https://docs.insforge.dev/introduction), [Supabase docs](https://supabase.com/docs), [Convex docs](https://docs.convex.dev/), [Model Context Protocol introduction](https://modelcontextprotocol.io/introduction). ## FAQ ### What is InsForge? InsForge is an open-source backend platform for agentic coding. It combines backend primitives such as Postgres, auth, storage, edge functions, a model gateway, compute, and deployment with agent-facing interfaces such as MCP, CLI commands, and skills. ### Is InsForge a Supabase alternative? Partly, but the more interesting framing is agent-native backend control plane. Supabase is a mature backend platform for human developers. InsForge is trying to make backend operations directly inspectable and operable by coding agents. ### Do coding agents need backend-specific tools? Yes, if they are expected to do more than edit frontend files. Backend work requires schema awareness, migration control, policy checks, logs, deployment state, and verification receipts. A general shell can do some of that, but a constrained backend surface can make the work safer and easier to review. ### Should teams migrate their backend for AI coding agents? Not by default. Start by making the existing backend legible: document schemas, expose safe CLI commands, add smoke tests, preserve migration receipts, and make logs easy to inspect. Consider an agent-native platform only if it improves control and verification over your current stack.

6 Launches in One Day: The DD Empire Expansion

Developers Digest — Thu, 07 May 2026 00:00:00 GMT

## 6 New Launches In One Day Today the empire grew by five apps and one Chrome extension. All shipped on the same day, all under [developersdigest.tech](https://developersdigest.tech), all wired into the same auth, deploy, and monitoring spine that runs the rest of the portfolio. Here is what each one is, why it exists, and where to follow along. ## ssl-watch - Free SSL + DNS Monitor [ssl-watch](/apps/ssl-watch) is a free SSL, DNS, and domain expiry monitor. Paste a domain once, get email or Slack alerts before a certificate, nameserver, or registration silently breaks production. Every dev I know has been bitten by this at least once. Most paid options are bundled into uptime suites you do not need. ssl-watch does the one thing. Coming soon: [/apps/ssl-watch](/apps/ssl-watch). ## ctx-peek - See Inside Your Claude Code Context [ctx-peek](/apps/ctx-peek) takes a Claude Code transcript and shows exactly what is in the context window - token by token, file by file, with bloat hotspots highlighted. If your agent suddenly gets dumber after 30 minutes, this is usually why. ctx-peek tells you which files are eating the budget and what to prune. Coming soon: [/apps/ctx-peek](/apps/ctx-peek). ## modelpick - Pick The Right Model In 4 Questions [modelpick](/apps/modelpick) is a decision-tree wrapper over the AI Models directory. Answer four questions about your task - latency tolerance, context size, modality, budget - and get back the optimal model, provider, and a price estimate per million tokens. It exists because nobody should have to memorize the difference between Sonnet 4.5, 4.6, and 4.7 to ship a feature. Coming soon: [/apps/modelpick](/apps/modelpick). ## dd-pulse - Live Status For Every DD App [dd-pulse](/apps/dd-pulse) is the live status and metrics dashboard for the entire DD portfolio. Uptime, deploy state, weekly active users, all in one page. We built it for ourselves first - running 25+ Coolify apps without a unified pulse view was getting silly - and then realized other multi-app builders need the same thing. Coming soon: [/apps/dd-pulse](/apps/dd-pulse). ## og-forge - Branded OG Images In 200ms [og-forge](/apps/og-forge) is a hosted OG-image API. Pass a URL or params, get back a branded preview card in roughly 200ms. Templates ship for blog posts, repos, products, and changelog entries. Every DD app already burns hours on per-product OG generators. og-forge collapses that into one endpoint with caching and a decent default look. Coming soon: [/apps/og-forge](/apps/og-forge). ## dd-extension - The Empire In Your Omnibar The Chrome extension is the connective tissue. Type `dd` in the omnibar, hit space, then a slug - `dd ssl-watch`, `dd modelpick`, `dd traces` - and you are in the right app. It also surfaces live status from dd-pulse and lets you save snippets straight into the content engine. If you use more than two DD apps a day, this is the launcher you want pinned. Install link drops with the public release. ## Empire Stats After Today The portfolio now spans **17 products** across **6 categories** - observability, content, agents, education, marketplaces, and developer utilities. Roughly **70% of active surface area is AI-coding focused**: agent tooling, model selection, context inspection, traces, skills, MCP servers. The rest is the infra that makes the AI-coding work pay rent - auth, payments, status, OG images, SSL. Same Coolify cluster. Same Convex + Clerk + Stripe stack. Same push-to-deploy pipeline. The cost of adding the sixth thing today was lower than the cost of adding the second thing six months ago, which is the entire point of building an empire on one spine instead of six. ## What Comes Next Each of the five apps is in `coming soon` state today. Public betas roll out across the next two weeks, in roughly the order listed above. The Chrome extension goes to the Web Store once we finish the review prep. If you want to be in the first wave, the [/apps](/apps) directory is the source of truth - every product gets a status pill the moment it goes live. No newsletter blast, no countdown, just the page updating. Six things shipped today. We will keep going.

DevDigest OS: The Thesis Behind Treating an Empire as One Operating System

Developers Digest — Thu, 07 May 2026 00:00:00 GMT

## One Question What if your dev tools weren't separate apps but one operating system? Not a suite. Not a platform. An OS - a shared substrate where every tool knows about every other tool, every output is an input somewhere else, and the catalog itself is a protocol other agents can read. That is the thesis behind [DevDigest OS](/os). It is also why we shipped [/suites](/suites). The marketing pages are the surface. This post is the argument. ## The Thesis in One Paragraph Each DevDigest app earns its place by solving exactly one thing well. None of them are platforms. None of them try to swallow your stack. But they share conventions - design language, auth, embeds, the apps catalog - and that shared layer is what turns a portfolio of single-purpose tools into something that behaves like an operating system for shipping. A platform asks you to migrate. An OS asks you to plug in. ## Each App Earns Its Place The rule is simple: if you can describe what an app does in one sentence and a developer nods, it ships. If the sentence needs an "and" or a "plus," it is two apps and we split it. - [ShipBadge](https://shipbadge.dev) - embed a "shipping today" badge on any project. - [DD Pulse](https://pulse.developersdigest.tech) - uptime + status pages for indie products. - [OG Forge](https://ogforge.dev) - generate social cards from a URL. - [ctx-peek](https://ctxpeek.dev) - peek at any AI agent's context window. - [TraceTrail](https://tracetrail.dev) - replay agent runs step by step. - [SponsorKit](https://sponsorkit.dev) - sponsor pages with one config file. Each of these is a complete product on its own. None require any of the others. That is intentional. The OS only works if every component survives being used in isolation. ## But Together They Loop The interesting work happens at the seams. **ShipBadge → DD Pulse → status pages on every app you ship.** You wire ShipBadge into a new repo. ShipBadge sees you also use DD Pulse and offers a one-click upgrade: the same badge now renders live uptime data. The status page DD Pulse generates embeds the badge back. Two apps, one feedback loop, no integration code. **OG Forge → ctx-peek → public profiles for your AI work.** ctx-peek captures an agent run. OG Forge auto-generates a social card from the trace. The profile page on ctx-peek embeds the OG Forge image and links back. You posted a tweet about an agent run; the tweet card was built by another DD app you forgot you owned. **TraceTrail → DD Pulse → reliability dashboards for agents.** TraceTrail records agent runs. DD Pulse turns the failure rate into an uptime metric. A status page now answers "is my agent reliable today" alongside "is my API up." These loops are not features we built. They emerged the moment two apps shared the same conventions. That is the OS dividend. ## Cross-App Conventions: The Real Product The apps are the demos. The conventions are the product. - **Every output is shareable.** Every artifact in every DD app has a public URL. No login walls on outputs. - **Every output is embeddable.** Every public URL has an embed variant - iframe, oEmbed, or Markdown shortcode. ShipBadge in your README, OG Forge in your blog, ctx-peek in your tweet. - **Every output links back.** Embeds carry attribution. The attribution is a link to the source app. The source app is the catalog entry. The catalog entry surfaces the next adjacent tool. Read those three rules in sequence and you have described how the empire compounds without us writing a single integration. ## The Chrome Extension as Desktop Shell If the apps are programs, the [DevDigest Chrome extension](/extension) is the desktop. It overlays the browser with a launcher, a clipboard that knows about every DD app, and context-aware actions on any page you visit. You are reading a Vercel dashboard? The extension offers "monitor with DD Pulse." You are looking at a GitHub repo? It offers "embed ShipBadge." You are debugging an agent in the Claude Code sidebar? It offers "open in TraceTrail." The extension is the only place a user sees the OS as a single thing. Everywhere else, the apps stay sharp and singular. That separation is on purpose. The shell is opinionated; the apps are not. ## /api/apps - The Catalog as Protocol The piece most people miss: [/api/apps](/api/apps) is a public JSON endpoint. It returns the entire DevDigest catalog - every app, its tagline, its embed schema, its OG-card endpoint, its status page. That endpoint is consumed by: 1. The Chrome extension launcher. 2. The [/suites](/suites) page. 3. Our own internal cross-promotion banners. 4. Third-party agents that want to introspect the empire. That last one is the lever. When an LLM agent asks "what tool can generate a social card from a URL," `/api/apps` is a single fetch away from a structured answer. The catalog is not marketing copy. It is a discovery protocol other software can consume. If you want your own indie portfolio to compound like this, expose your catalog. Make it boring JSON. Make it fetchable without auth. The agents are coming for the rest. ## What This Is Not DevDigest OS is not: - **A platform.** You do not host on it. You do not deploy to it. There is no SDK lock-in. - **A bundle.** You do not buy "the suite." Every app prices independently. - **A monolith.** No app shares a database with another. The shared layer is conventions, not infrastructure. - **Finished.** The catalog grows whenever a tool earns its sentence. If any of those become true, we have lost the plot. Drift toward platform is the failure mode. ## The Compounding Argument Here is the only number that matters: the marginal utility of the *next* DD app is higher than the last. When we shipped ShipBadge alone, it was a badge service. When DD Pulse landed, ShipBadge became a status indicator. When OG Forge landed, both got social cards for free. When ctx-peek landed, all three got agent-run trace embeds. Every new app makes the previous apps more useful - not because we rewrite them, but because the conventions hold and the catalog updates. That is the definition of an operating system: the shared substrate is what creates leverage. A monolith compounds linearly. A pile of apps does not compound at all. An OS - small, sharp tools plus shared conventions plus a public catalog - compounds. ## What To Do Next If you build indie products, steal the pattern: 1. One app, one sentence. If you cannot explain it without "and," split it. 2. Every output gets a public URL, an embed, and a link back. 3. Publish a `/api/apps`-style catalog. JSON, no auth, stable schema. 4. Build a shell only after you have three apps. Not before. If you want to see it in motion, the [/os](/os) page is the live tour and [/suites](/suites) is the catalog grouped by job-to-be-done. Everything on both pages is pulled from the same `/api/apps` endpoint that the agents read. The empire is not the apps. The empire is the layer underneath that makes the apps stop being separate.

Terminal Agents Are Becoming Portable Runtime Surfaces

Developers Digest — Thu, 07 May 2026 00:00:00 GMT

DeepSeek-TUI hit the front page of GitHub trending because it is easy to describe: Claude Code, but wired around DeepSeek models. That framing is useful, but it undersells the bigger shift. The interesting part is not the clone label. The interesting part is that the agent runtime is becoming portable. The [DeepSeek-TUI repo](https://github.com/Hmbown/DeepSeek-TUI) describes a terminal coding agent with local file editing, shell execution, git operations, subagents, MCP servers, approval modes, rollback snapshots, durable background tasks, an HTTP/SSE runtime API, LSP diagnostics, skills, and live cost tracking. Whether that particular project becomes a daily driver is less important than what it proves: developers now expect the terminal agent surface to be separable from one model vendor. ## Quick verdict - If you are choosing a coding agent today, start with [/compare](/compare) and [/pricing](/pricing). - If you want a deeper three-way decision, start with [Claude Code vs Cursor vs Codex](/blog/claude-code-vs-cursor-vs-codex-2026). - If you are evaluating DeepSeek-TUI specifically, start with the tool card: [/tools/deepseek-tui](/tools/deepseek-tui). That is the same market pressure behind [free Claude Code model gateways](/blog/free-claude-code-model-gateway-tradeoffs), [Codex goals](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences), and the newer [Claude Code token-burn observability debate](/blog/claude-code-token-burn-cache-observability). The work is no longer "can the model edit code?" The work is "can the runtime supervise edits safely, cheaply, and repeatably?" ## The Runtime Is The Product AI coding agents started as model demos. Ask for a function, get a diff. Ask for a test, get a test. The model was the product. That era is over for serious work. The model still matters, but the product surface has moved to the runtime around the model: - how the agent asks for permission before risky commands - how it snapshots state before a turn - how it restores a bad edit - how it shows diagnostics after changing files - how it compacts context before cost explodes - how it reports token spend and cache behavior - how it lets subagents split work without losing receipts - how it resumes after a restart - how it exposes a headless API for loops and CI DeepSeek-TUI's feature list reads like a checklist for that runtime layer. Plan, Agent, and YOLO modes are not model features. Rollback snapshots are not model features. LSP diagnostics are not model features. Durable task queues are not model features. They are harness features. That is why this belongs next to [long-running agents need harnesses, not hope](/blog/long-running-agents-need-harnesses). Once an agent can touch a real repo, the harness becomes the difference between "neat demo" and "tool I can leave alone for 20 minutes." ## The Portability Pressure Is Real Developers do not want one perfect agent. They want a stable operating model that can survive model churn. Today that might mean Claude Code for planning-heavy repo work, Codex for background tasks and review loops, Cursor for inline IDE edits, and a DeepSeek or Qwen-backed tool for cheaper exploratory passes. Tomorrow it will be a different mix. The platform that wins is the one that makes those swaps boring. The DeepSeek-TUI README is explicit that `auto` is a local routing mode: the runtime decides whether a turn should use Flash or Pro and what thinking level it needs before sending a concrete model request upstream. That is the right shape. Model routing should be visible, local, and accountable. If a cheap model handled the job, show that. If a harder turn moved up to the stronger model, show that too. This is also where [Codex vs Claude Code](/blog/codex-vs-claude-code-april-2026) comparisons need to mature. "Which model is smarter?" is too shallow. The real questions are: - Can I pin model choice for repeatable benchmarking? - Can I set a cost ceiling before the run starts? - Can I inspect why a router escalated? - Can I keep the same approval policy across providers? - Can I replay the run after a bad edit? - Can I export the session as evidence? That is what portable agent infrastructure looks like. ## Why The Clone Critique Is Too Easy The obvious opposing take is fair: a lot of AI developer tools are derivative. A fast GitHub trend can be novelty, not staying power. A Claude Code-shaped terminal app with another backend does not automatically become production infrastructure. There are real risks: - Approval modes can look safe while still allowing dangerous shell paths. - Rollback snapshots can give false confidence if generated files, databases, or external services changed outside git. - Cost telemetry can be approximate if provider accounting is opaque. - Subagents can multiply confusion if they do not leave clean receipts. - Skills can rot into another prompt pile if they are not short and tested. - A fast-moving repo can have gaps in security review, package provenance, or dependency discipline. That critique matters. The right answer is not to install every trending agent. The right answer is to evaluate the runtime primitives one by one. This is the same point behind [agent swarms need receipts](/blog/agent-swarms-need-receipts). More agents are not automatically better. More visible state is better. More rollback control is better. More deterministic verification is better. ## What A Serious Terminal Agent Needs If a team is evaluating DeepSeek-TUI, Codex, Claude Code, Cursor CLI, Kimi, Droid, or any other terminal agent, I would score the runtime before the model. ### 1. Permission Boundaries The minimum viable control plane is not "ask before shell." It is a permission system that separates read-only exploration, interactive editing, and auto-approved execution. Claude Code has permissions, hooks, and settings. Codex has permission profiles and sandboxing. DeepSeek-TUI advertises Plan, Agent, and YOLO modes. Different names, same requirement: the agent should know when it is allowed to observe, edit, execute, and escalate. The best runtimes make the policy visible in the UI and hard to bypass accidentally. ### 2. Rollback And Repro Rollback has to be more than "git checkout." A useful runtime should know what changed during a turn, what commands ran, what diagnostics appeared afterward, and what state can be restored without touching the repo's main `.git` history. DeepSeek-TUI's side-git snapshot idea is interesting because it treats rollback as an agent-runtime concern rather than a human cleanup chore. For production teams, rollback should pair with replay. If an agent made a risky edit, you need to know the exact instruction, tool calls, diff, and verification output that led there. That is why [agent replays](/blog/agent-replays-with-tracetrail) and local transcripts matter. ### 3. Diagnostics In The Loop The model should not wait for a human to paste TypeScript errors back into chat. DeepSeek-TUI advertises LSP diagnostics after edits through tools like rust-analyzer, pyright, typescript-language-server, gopls, and clangd. That is the right direction. The runtime should feed compiler and language-server feedback into the next turn automatically, because that is how real coding works. Codex and Claude Code users already do this manually by running `pnpm typecheck`, `cargo test`, `go test`, or focused linters. A stronger runtime makes the common loop automatic while still leaving the final verification command explicit. ### 4. Cost And Cache Telemetry The latest [Claude Code token burn post](/blog/claude-code-token-burn-cache-observability) makes the same point from the other side: coding agents need a usage dashboard that developers can debug. DeepSeek-TUI claims live cost tracking plus cache hit/miss breakdowns. That is exactly the category to watch. A terminal agent should show: - model selected - thinking level selected - input and output tokens - cached versus uncached input - per-turn estimated cost - session total - router decisions - context compaction events Without that, "cheap model" can become expensive by accident. With it, a team can choose when to route cheap, when to route smart, and when to stop. ### 5. Background Work With Stop Conditions Durable task queues and HTTP/SSE runtime APIs sound like implementation details, but they are the bridge from chat to operations. A terminal agent that can survive restarts and expose headless control can become a loop: watch a PR, fix deterministic CI failures, re-run tests, report when blocked, and stop when the same failure repeats. That is the [Codex loops](/blog/codex-loops-boris-cherny-agent-routines) lane. The hard part is not starting background work. The hard part is making it stop clearly. ## The Buying Criteria Changed The old buyer question was: > Which AI coding model writes the best code? The new buyer question is: > Which agent runtime lets my team supervise model work without losing control? That changes the shortlist. A great model with weak approvals is risky. A cheap model with no telemetry is not really cheap. A fast agent with no rollback is a liability. A beautiful UI with no headless API is limited to interactive work. A swarm system with no receipts is just parallel uncertainty. This is why DeepSeek-TUI is a useful signal even if you never install it. It shows what developers now expect from an open terminal agent: - multiple model routes - local workspace control - approval modes - rollback - diagnostics - skills - subagents - MCP - cost telemetry - resumable sessions - background execution That list is becoming table stakes. ## My Take Do not treat DeepSeek-TUI as "the Claude Code clone of the week." Treat it as evidence that the terminal-agent runtime is becoming a commodity surface. That is good for developers. It means the useful parts of agent systems are being named, copied, tested, and recombined. It also means the bar should go up. If a new coding agent launches without approvals, rollback, diagnostics, cost telemetry, session export, and clear provider routing, it is not competing with Claude Code or Codex. It is competing with last year's demo. The next durable layer is not one more chat window. It is the portable agent runtime: a control plane where models can change, but the team's operating rules stay intact. Sources: [DeepSeek-TUI on GitHub](https://github.com/Hmbown/DeepSeek-TUI), [OpenAI Codex app announcement](https://openai.com/index/introducing-the-codex-app/), [Claude Code features overview](https://code.claude.com/docs/en/features-overview), [Claude Code hooks reference](https://docs.anthropic.com/en/docs/claude-code/hooks), [Claude Code subagents docs](https://code.claude.com/docs/en/sub-agents). ## FAQ ### What is DeepSeek-TUI? DeepSeek-TUI is an open-source terminal coding agent built around DeepSeek models. It can read and edit local files, run shell commands, manage git workflows, use subagents, connect to MCP servers, report cost telemetry, and expose a terminal UI for supervised agent work. ### Is DeepSeek-TUI just a Claude Code clone? It is clearly inspired by Claude Code-style terminal agent workflows, but the more useful way to read it is as a portable runtime experiment. The important question is not whether it resembles another tool. The important question is whether its approvals, rollback, diagnostics, cost tracking, and model routing are strong enough for real work. ### Why do terminal agents need rollback? Terminal agents can edit files, run commands, and change local state. Rollback gives the user a way to inspect and recover from a bad turn without manually reconstructing every change. For serious use, rollback should be paired with transcripts, diffs, command logs, and verification output. ### Should teams use multiple coding agents? Yes, but only with clear boundaries. One agent might be better for planning, another for background review, another for cheap exploratory work, and another for IDE edits. The key is to keep the runtime rules consistent: permissions, tests, receipts, cost limits, and escalation paths. ### What should I look for before adopting a new terminal agent? Start with the runtime, not the model. Check permission modes, sandbox behavior, rollback, transcript export, diagnostics, context compaction, cost telemetry, model routing, subagent isolation, and whether the tool can run headless for CI or recurring workflows. Then benchmark model quality inside your own repo.

What Is Cline? The Open-Source AI Coding Tool That Runs in VS Code

Developers Digest — Thu, 07 May 2026 00:00:00 GMT

Cline is an open-source VS Code extension that turns your editor into an autonomous AI coding environment. Unlike autocomplete tools that suggest the next line, Cline operates as an agent - it reads files, writes code, runs terminal commands, and iterates on errors without constant hand-holding. The tool is free to install. The code is open source under the Apache 2.0 license. You bring your own API key for cloud models like Claude or OpenAI models, or you run local models through Ollama and pay nothing at all. This guide covers what Cline is, how it compares to paid alternatives, and whether it fits your workflow. ## Quick verdict Cline is the best open-source VS Code agent if you want model choice and control. It is a great fit when you want agentic workflows (multi-file edits, command runs, error recovery) without switching editors or locking into one vendor. - Want the short tool-card summary? Start at [Cline in the tools directory](/tools/cline). - If you want a more polished integrated UX, start with [Cursor](/blog/what-is-cursor-ai-code-editor-2026) or [Windsurf](/blog/windsurf-vs-cursor). - If you want a terminal-native agent workflow, start with [Claude Code](/blog/what-is-claude-code-complete-guide-2026) or [Codex](/blog/openai-codex-guide). - If cost is the deciding factor, start with the [pricing hub](/pricing) and the [AI coding tools pricing table](/blog/ai-coding-tools-pricing-2026). ## Why Cline Exists The AI coding market split into two camps. On one side: commercial products like [Cursor](/blog/what-is-cursor-ai-code-editor-2026), [Windsurf](/blog/windsurf-vs-cursor), and [GitHub Copilot](/blog/github-copilot-guide) that bundle models, UX, and subscriptions together. On the other side: open-source tools that prioritize flexibility and user control. Cline sits in the second camp. It does not try to replace your editor - it adds AI capabilities to the VS Code you already use. It does not lock you into a single model provider - it connects to whatever backend you configure. And it does not charge a subscription - you own the tool. For developers who want agentic AI coding without vendor dependencies, Cline is the most capable open-source option available in VS Code. ## What Cline Can Do Cline is an agent, not an autocomplete engine. The difference matters. Autocomplete tools (like basic Copilot) predict the next tokens based on your cursor position. They are reactive. You write, they suggest. Agentic tools (like Cline, [Claude Code](/blog/what-is-claude-code-complete-guide-2026), and [Codex](/blog/openai-codex-guide)) make decisions. You describe a task, and the agent figures out which files to read, what code to write, which commands to run, and how to fix errors when things break. Cline's core capabilities include: **Multi-file code generation.** Cline reads your project structure and writes code across multiple files in a single task. If you ask it to add a feature, it might create a new component, update imports, modify tests, and adjust configuration - all without you specifying each file. **Terminal command execution.** Cline runs shell commands directly. It can install dependencies, run builds, execute tests, and read output. When a command fails, it sees the error and attempts to fix the underlying code. **File system access.** Cline reads files and directories (respecting `.gitignore`), writes new files, and edits existing ones. It understands project context because it can actually see your code. **MCP (Model Context Protocol) support.** Cline integrates with [MCP servers](/blog/what-is-mcp) for extended capabilities - database access, API connections, browser automation, and custom tools. This makes Cline extensible beyond its built-in features. **Multi-model flexibility.** Cline works with local models through Ollama, or cloud models through API keys for Claude, OpenAI models, Gemini, Azure OpenAI, and others. You choose the model based on task, cost, and privacy requirements. **Iterative error correction.** When something fails - a test, a build, a command - Cline reads the output and tries again. This loop continues until the task succeeds or you intervene. The combination makes Cline a genuine coding agent rather than a fancy autocomplete. ## How Cline Works Cline runs as a VS Code extension with a sidebar panel. You open the panel, describe what you want, and Cline executes. The interaction model is chat-based, similar to ChatGPT or Claude. But unlike web chat interfaces, Cline has direct access to your workspace. It does not need you to paste code snippets or describe file contents - it reads them directly. A typical workflow looks like: 1. You describe a task: "Add error handling to the API routes in `src/api/`" 2. Cline reads the relevant files to understand the current code 3. Cline proposes changes and explains its approach 4. You approve (or Cline auto-executes if you have enabled that mode) 5. Cline writes the changes across all affected files 6. Cline runs tests or builds to verify 7. If errors appear, Cline reads the output and adjusts The agent loop continues until the task is complete or you stop it. ## Model Options Cline is model-agnostic. You pick the backend. ### Cloud Models For cloud models, you paste an API key and Cline calls the provider directly: - **Anthropic Claude** - Claude Sonnet and Opus through the Anthropic API - **OpenAI** - OpenAI models (GPT and more) - **Google Gemini** - Gemini Pro and Ultra through the Google AI API - **Azure OpenAI** - Enterprise deployments with Azure endpoints - **OpenRouter** - A proxy that routes to multiple providers Cloud models offer the strongest reasoning quality, especially Claude Opus and higher-tier OpenAI models. The tradeoff is cost (you pay per token) and data leaving your machine. ### Local Models For local models, Cline connects to Ollama running on your machine: ```bash # Install Ollama from https://ollama.ai ollama pull deepseek-coder-v2 # A strong coding model ollama serve # Start the local server ``` Then configure Cline to use Ollama as the provider. Local models keep everything on your hardware. No API costs, no data transmitted. The tradeoff is model quality - even the best local models lag behind Claude Opus or higher-tier OpenAI models on complex reasoning tasks. Popular local options for coding: - **DeepSeek Coder V2** - Strong code generation, relatively fast - **Mistral** - Good general-purpose model - **CodeLlama** - Meta's code-focused model - **Qwen2.5-Coder** - Alibaba's coding model with good performance For most developers, a hybrid approach works best: use local models for routine tasks and cloud models for complex work that needs stronger reasoning. ## Installation Setup takes about five minutes. ### Step 1: Install the Extension Open VS Code, go to Extensions (Cmd+Shift+X / Ctrl+Shift+X), search for "Cline", and install the extension by Saoudrizwan. ### Step 2: Configure a Model Click the Cline icon in the sidebar to open the panel. Choose your model provider: **For cloud models:** Select the provider (Anthropic, OpenAI, etc.) and paste your API key. **For local models:** Install Ollama, pull a model, run `ollama serve`, then select Ollama in Cline's settings. ### Step 3: Start Coding Type a task in the chat panel. Cline will ask for permission before reading files or running commands (unless you enable auto-approve). That is the basic setup. For the current recommended install and onboarding paths, follow the official docs. ## Cline vs. Paid Alternatives The natural question: why use Cline instead of Cursor, Windsurf, or Copilot? ### Cline vs. Cursor [Cursor](/blog/cursor-ai-code-editor-guide) is a proprietary VS Code fork with integrated AI. It costs $20/month for Pro or $200/month for unlimited usage. Cursor's UX is polished - inline diffs, composer mode, and tight model integration. Cline is free and works inside standard VS Code. You keep your existing extensions, settings, and keybindings. But Cline's UI is simpler (a sidebar panel rather than Cursor's multi-mode interface), and you manage model configuration yourself. **Choose Cline if:** You want open source, existing VS Code setup, or local model support. **Choose Cursor if:** You want a polished all-in-one product and do not mind vendor lock-in. ### Cline vs. Windsurf [Windsurf](/blog/windsurf-vs-cursor) (formerly Codeium) is another proprietary AI editor. It has a generous free tier and costs $15/month for Pro. Windsurf's Cascade agent handles multi-step tasks well. Cline is comparable in agentic capabilities but trades commercial polish for open-source flexibility. Windsurf has better out-of-box model optimization; Cline has better extensibility through MCP. **Choose Cline if:** Open source and model flexibility matter more than integrated UX. **Choose Windsurf if:** You want a free or low-cost commercial product with less setup. ### Cline vs. GitHub Copilot [Copilot](/blog/github-copilot-guide) excels at autocomplete. It suggests code as you type and integrates deeply with GitHub. Copilot's agentic features (Copilot Chat, Copilot Agent) are improving but still behind dedicated agent tools. Cline is more autonomous. It writes across files, runs commands, and iterates on errors. Copilot's strength is in-line suggestions during manual coding; Cline's strength is task delegation. **Choose Cline if:** You want an autonomous agent rather than autocomplete. **Choose Copilot if:** You want tight GitHub integration and inline suggestions while you code. ### Cline vs. Claude Code [Claude Code](/blog/what-is-claude-code-complete-guide-2026) is Anthropic's terminal-based agent. It is not open source, requires an Anthropic subscription ($20-$200/month), and runs in the terminal rather than VS Code. Claude Code has stronger reasoning (Opus access) and a more mature sub-agent architecture. Cline has VS Code integration and model flexibility. **Choose Cline if:** You want to stay in VS Code and use multiple model providers. **Choose Claude Code if:** You want the strongest reasoning quality and prefer terminal workflows. ### Cline vs. Aider [Aider](/blog/aider-vs-claude-code-2026-update) is another open-source CLI tool for AI coding. It runs in the terminal, supports multiple models, and focuses on git-aware editing. Cline has VS Code integration; Aider is terminal-only. Both are open source and model-agnostic. Aider has more mature git integration; Cline has MCP extensibility. **Choose Cline if:** You prefer working inside VS Code. **Choose Aider if:** You prefer terminal workflows and value git integration. ## When Cline Makes Sense Cline fits specific developer profiles: **Privacy-conscious developers.** With local models, code stays on your machine. With cloud models, code goes to the provider you configure. **Open-source advocates.** Apache 2.0 license means you can fork, modify, and audit the code. **Multi-model testers.** If you evaluate different models for different tasks, Cline's provider flexibility helps. **VS Code loyalists.** If your workflow depends on VS Code extensions and settings, Cline adds AI without requiring a new editor. **Budget-constrained developers.** Free tool plus cheap API calls (or free local models) beats $20-$200/month subscriptions. **Enterprise teams with data restrictions.** Local-first operation satisfies strict data governance requirements. ## When Cline Does Not Make Sense Cline has tradeoffs: **No commercial support.** If something breaks, you file a GitHub issue and wait for community response. No SLA, no phone support, no enterprise contracts. **Setup required.** Getting optimal performance requires configuring providers, tuning prompts, and sometimes debugging MCP integrations. Cursor and Windsurf work out of the box. **Weaker models locally.** Local models through Ollama are capable but not Claude-Opus-tier. For complex architectural work, you need cloud APIs (and their costs). **Less polished UX.** Cline's sidebar interface is functional but lacks Cursor's inline diffs and composer mode. The interaction is more chat-like than integrated. If you want zero-setup, polished UX, and commercial accountability, paid tools like Cursor or Claude Code are better choices. ## Practical Tips A few patterns that work well with Cline: **Start with a plan.** Before asking Cline to code, describe what you want at a high level. "Add authentication to the API" is better than "fix login." **Let it read first.** Point Cline at the relevant files before asking for changes. Context improves output quality. **Use cloud models for complex tasks.** Save local models for routine work. Switch to Claude or higher-tier OpenAI models when reasoning quality matters. **Enable MCP for extended workflows.** If you need database access, browser testing, or API integrations, configure MCP servers to expand Cline's capabilities. **Review before committing.** Cline edits files directly. Review diffs in VS Code's source control panel before committing changes. ## The Bottom Line Cline is the best open-source AI coding agent for VS Code. It brings autonomous capabilities - multi-file editing, terminal execution, iterative error correction - without subscriptions or vendor lock-in. The tradeoff is setup effort and polish. Cursor and Windsurf are easier to start with. Claude Code has stronger reasoning. But if open source, model flexibility, and VS Code integration matter to you, Cline is the right choice. For developers already paying for Claude or OpenAI API access, Cline is effectively free. For developers willing to run local models, it costs nothing at all. Install it from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.cline), configure a model, and try delegating a real task. That is the only way to know if agentic AI coding fits your workflow. ## Sources - Official site: https://cline.bot/ - Official docs: https://docs.cline.bot/ - GitHub repo: https://github.com/cline/cline - License (Apache 2.0): https://github.com/cline/cline/blob/main/LICENSE - VS Code Marketplace listing: https://marketplace.visualstudio.com/items?itemName=saoudrizwan.cline ## Frequently Asked Questions ### Is Cline free? Yes. Cline is open source under the Apache 2.0 license with no licensing fees. You only pay for cloud model API calls if you use Claude, OpenAI models, or similar providers. Using local models through Ollama is completely free. ### What models does Cline support? Cline works with cloud providers (Anthropic Claude, OpenAI, Google Gemini, Azure OpenAI, OpenRouter) and local models through Ollama. You configure the provider and paste your API key. For local models, you run Ollama on your machine and Cline connects automatically. ### How does Cline compare to Cursor? Cursor is a proprietary VS Code fork with integrated AI at $20-$200/month. Cline is a free VS Code extension. Cursor has a more polished UI with inline diffs and composer mode. Cline keeps you in standard VS Code with your existing setup. Choose Cursor for polish; choose Cline for open source and flexibility. ### Can Cline run terminal commands? Yes. Cline executes shell commands directly, including builds, tests, package installations, and git operations. It reads command output and uses errors to guide subsequent fixes. You can configure approval requirements for command execution. ### What is MCP and why does Cline support it? MCP (Model Context Protocol) is a standard for extending AI agent capabilities. Cline uses MCP to connect to databases, APIs, browsers, and custom tools beyond its built-in features. This makes Cline extensible - you add capabilities without modifying the core tool. ### Is Cline good for large codebases? Cline handles project-wide context reasonably well, but performance depends on your model choice. Cloud models like Claude handle large context windows better than most local models. For very large monorepos, you may need to scope tasks to specific directories. ### How does Cline handle errors? When a command or build fails, Cline reads the error output and attempts to fix the underlying code. This loop continues iteratively until the task succeeds or you stop it. The error recovery is one of Cline's strengths compared to simpler autocomplete tools. ### Should I use local models or cloud models? Use local models (Ollama) for routine tasks, privacy-sensitive work, and cost savings. Use cloud models (Claude, OpenAI models) for complex reasoning, architectural decisions, and tasks where quality matters more than cost. Many developers use both, switching based on the task. ## Related Guides - [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026) - Full comparison of the AI coding landscape - [AI Coding Tools Pricing Comparison](/blog/ai-coding-tools-pricing-2026) - Cost breakdown for every major tool - [What Is Claude Code?](/blog/what-is-claude-code-complete-guide-2026) - Anthropic's terminal-based AI agent - [Cursor AI Guide](/blog/cursor-ai-code-editor-guide) - Deep dive on the leading proprietary AI editor - [Aider vs Claude Code](/blog/aider-vs-claude-code-2026-update) - Open-source CLI tool comparison

Claude Code Token Burn Is an Observability Problem

Developers Digest — Wed, 06 May 2026 00:00:00 GMT

Claude Code token burn is back in the feed. The current viral thread started with Alexander Zanfir's writeup, [Claude Diagnosed Its Own Cache Bug](https://medium.com/@alexzanfir/claude-diagnosed-its-own-cache-bug-a-six-month-timeline-332f577e1fe9). The useful part is not whether every claim in the timeline is proven from the outside. The useful part is that a coding agent was asked to audit its own usage, found suspicious cache-flush behavior, and produced a trail that other users could argue with. That is where the AI coding market is headed. Not "trust the quota bar." Not "trust a Reddit screenshot." Agent usage needs repro-grade observability. If you are already running [Claude Code](/blog/what-is-claude-code-complete-guide-2026), this belongs next to the [Claude Code usage limits playbook](/blog/claude-code-usage-limits-playbook-2026), [agent FinOps](/blog/400-dollar-overnight-bill-agent-finops), and the recent [Claude Code ops release](/blog/claude-code-2-1-128-mcp-ops). The product keeps getting more capable. The accounting layer has to catch up. ## What actually changed Anthropic did publish an official postmortem on April 23: [An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem). It traced the recent quality issues to three separate changes: - a reasoning-effort default change that was later reverted - a stale-session thinking-cache bug that caused repeated cache misses - a system prompt change that hurt coding quality The cache section matters most for token burn. Anthropic says the bug caused old thinking to be cleared every turn after a stale session crossed an idle threshold. That made Claude seem forgetful and repetitive, and Anthropic wrote that it likely drove reports of usage limits draining faster than expected. So the simplified take, "Anthropic never acknowledged anything," is wrong. Zanfir's article now includes a correction on that point. But the opposing simplified take, "the postmortem means this is over," is also too neat. Users are still reporting confusing usage behavior, the community is still building monitors and workarounds, and Anthropic's own support docs still explain usage in broad plan-level terms rather than session-level cache health. The lesson is not that every complaint is a confirmed bug. The lesson is that coding-agent usage needs better local evidence. ## Cache misses are a product issue Prompt caching is usually explained as infrastructure. It should be treated as product behavior. When a coding agent is working in a large repo, the difference between a healthy cache and a broken cache can be the difference between a useful Max session and a five-hour reset that arrives before the patch is done. Anthropic's [usage-limit docs](https://support.anthropic.com/en/articles/11647753-understanding-usage-and-length-limits) say usage depends on conversation length, model, features, and product surface. Their [cost-management docs](https://docs.anthropic.com/en/docs/claude-code/costs) also point API users toward historical usage and workspace spend limits. That is useful, but it is not enough for serious agent work. A developer running a long Claude Code session needs to know: - how many input tokens were cached versus uncached - whether cache reads collapsed after resume - whether thinking blocks are being retained or pruned - whether MCP calls, subagents, or skills changed the prompt prefix - which turn caused a quota cliff - whether the next request is likely to rebuild the whole context That is not billing trivia. It changes whether you continue the session, compact, restart, split the task, switch models, or stop and file a bug. ## The community is building the missing gauges This is why the most interesting GitHub signal is not another wrapper promising free usage. It is tooling like [cc-cache-monitor](https://github.com/AlexZan/cc-cache-monitor), which tries to inspect Claude Code logs and surface cache behavior. Whether that specific project becomes the standard is less important than the pattern. Developers want the agent equivalent of a network waterfall: - turn number - model - input tokens - output tokens - cache reads - cache writes - cache misses - tool calls - estimated cost - session reset events That is the same argument behind [agent receipts](/blog/agent-swarms-need-receipts). Once agents run for hours, "it felt expensive" is not acceptable debugging data. ## The fair critique There is a fair critique of the community reaction: local reverse engineering can overfit. Claude Code is a hosted product, a local CLI, an API client, a model harness, a prompt layer, and a quota system at the same time. A user can observe symptoms, logs, and billing effects, but not every server-side decision. Cache behavior can change because of TTLs, model routing, product experiments, stale sessions, prompt changes, or user configuration. That means public bug claims should be written with care. But that is exactly why first-party observability matters. When the official product does not expose enough session-level telemetry, the community fills the gap with scripts, screenshots, Reddit threads, and partial reconstructions. Some will be right. Some will be wrong. All of them become louder than they need to be because the product does not provide the obvious facts. ## What Claude Code should expose Claude Code does not need to expose private chain-of-thought or internal prompts to fix this class of problem. It needs operational counters. Minimum viable usage telemetry: | Counter | Why it matters | |---|---| | `cache_read_tokens` | Shows whether reused context is actually cheap | | `cache_write_tokens` | Shows when the session is rebuilding expensive prefixes | | `uncached_input_tokens` | Separates real new work from repeated context cost | | `output_tokens` | Identifies verbosity and overthinking failures | | `thinking_budget` | Shows whether effort settings are driving cost | | `tool_call_count` | Catches runaway searches, MCP loops, and file rereads | | `session_age` | Makes idle-resume behavior visible | | `estimated_plan_usage` | Translates technical counters into quota impact | Expose it in `/usage`, export it as JSON, and let hooks read it. That would make Claude Code easier to trust without weakening the product. For teams, the same shape should become an OpenTelemetry stream. We covered the broader [managed-agent FinOps problem](/blog/400-dollar-overnight-bill-agent-finops), but Claude Code is the cleanest consumer example: the user needs one trace per agent run, with model calls and tool calls under it, tagged with usage counters and cost estimates. ## What to do this week Do not wait for the perfect official dashboard. 1. Upgrade Claude Code and read the release notes before assuming old workarounds still apply. 2. Start long tasks in fresh sessions when cache behavior feels suspicious. 3. Use `/compact` or split tasks before the context gets huge. 4. Track session-level cost or quota burn outside the chat transcript. 5. Add stop hooks that halt repeated failing loops before they become quota loops. 6. Keep a short repro log: version, model, effort setting, session age, resume behavior, and whether MCP/subagents/skills were active. The goal is not paranoia. The goal is to make usage complaints debuggable. ## The take The cache-burn controversy is not a reason to abandon Claude Code. It is a reason to operate it like infrastructure. Claude Code is becoming a serious agent runtime: subagents, hooks, MCP, worktrees, skills, plugins, and long-running loops. Serious runtimes need serious counters. If prompt caching saves quota, developers should be able to see it. If a stale session starts rebuilding context, developers should be able to catch it before the five-hour reset. The next differentiator in AI coding tools will not just be model quality. It will be whether the tool can explain what it spent. ## Sources - Anthropic: [An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem) - Anthropic Help Center: [Understanding usage and length limits](https://support.anthropic.com/en/articles/11647753-understanding-usage-and-length-limits) - Anthropic Docs: [Manage costs effectively](https://docs.anthropic.com/en/docs/claude-code/costs) - Alexander Zanfir: [Claude Diagnosed Its Own Cache Bug](https://medium.com/@alexzanfir/claude-diagnosed-its-own-cache-bug-a-six-month-timeline-332f577e1fe9) - GitHub: [cc-cache-monitor](https://github.com/AlexZan/cc-cache-monitor) ## Frequently Asked Questions ### Why is Claude Code using so much quota? Claude Code usage depends on model choice, effort setting, conversation length, tool use, attached context, and cache behavior. If a long session repeatedly rebuilds context instead of reading from cache, quota can drain much faster than the visible response length suggests. ### Did Anthropic confirm a Claude Code cache bug? Yes. Anthropic's April 23 postmortem says a stale-session thinking-cache bug caused prior reasoning to be dropped every turn after an idle threshold and likely contributed to reports of usage limits draining faster than expected. Anthropic says that specific issue was fixed on April 10 in v2.1.101. ### Does that mean every current token-burn complaint is the same bug? No. Current reports can come from old client versions, long context, effort settings, MCP behavior, subagents, server-side cache eviction, or unrelated product issues. That is why session-level telemetry matters. ### How do I monitor Claude Code cache behavior? Start by checking Claude Code's built-in usage view and keeping session metadata for suspicious runs. Community tools like `cc-cache-monitor` are emerging to inspect local logs, but treat them as diagnostic aids rather than official billing truth. ### What should Claude Code expose in `/usage`? At minimum: cached input tokens, uncached input tokens, cache writes, output tokens, thinking budget, tool-call count, session age, model, effort setting, and estimated quota impact per turn. ### Should teams stop using long-running Claude Code sessions? No. Long sessions are still useful for deep coding work. Teams should add iteration caps, stop hooks, fresh-session checkpoints, and usage telemetry so long runs fail visibly instead of quietly burning quota.

How We Patched 100+ PRs Across Our App Empire in One Day

Developers Digest — Wed, 06 May 2026 00:00:00 GMT

## The Audit The Developers Digest empire is now 31 apps deployed across `*.developersdigest.tech`. That number snuck up on me. Each app started life from the same starter template, but templates drift the moment you fork them. Favicons go missing. Someone forgets to wire Google Analytics. The OG card pattern that worked last quarter quietly stops getting copied forward. By the time you have 24 production apps, the variance between them is louder than the consistency. So I ran a parallel `curl` audit across all 31 hosts. The matrix that came back was not pretty. **Reachability:** 24 of 31 apps responded with a 200. Seven were down - three returning 5xx (`agentfs`, `hookyard`, `tracetrail`) and four totally unreachable (`agent-eval-bench`, `cost-tape`, `hooks-directory`, `migrate`, `skill-builder`). Two of the dead hosts were still being linked from the public `/apps` page. That alone was an emergency. **Drift across the 24 reachable apps:** | Check | Coverage | Missing | |---|---|---| | favicon.ico | 17% | 20 / 24 | | llms.txt | 29% | 17 / 24 | | OG (full 3/3) | 46% | 13 / 24 | | sitemap.xml | 75% | 6 / 24 | | robots.txt | 75% | 6 / 24 | | GA tag | 75% | 6 / 24 | | Sentry init | 0% | 24 / 24 | The Sentry zero stung. The favicon number was the embarrassing one - empty browser tabs across most of the empire. ## The Fanout The interesting part is what happened next. Instead of opening one big "fix everything" PR, I treated each missing piece as a fanout job. One audit, one fix template, dozens of agents, one PR per repo. Here is the day's PR ledger: - **9 `chore: add llms.txt` PRs** - **17 `chore: add favicon.ico` PRs** - **4 `chore: add Google Analytics tracking` PRs** - **16 `chore: add Sentry` PRs** (queued; pending source-tree confirmation) - **4 robots.txt + sitemap.xml route handler PRs** - **8 OG image / metadata PRs** - **35 `migrate: replit -> coolify + neon + clerk` PRs** (a separate but parallel migration sweep) - **2 `developers-digest-site` apps-page PRs** (one to add Neon Data Lite, one to mark unreachable apps as Coming Soon so the public page stops linking to dead hosts) **Total open PRs by end of day: 58**, with a separate ledger of in-progress Sentry/OG batches still being prepped. Counted with the not-yet-opened batches, the day's pipeline was over 100 PRs. ## Status by Merge State Of the 58 PRs that landed in GitHub today: - **40 are CLEAN** - no failing checks, ready for `@devin-ai-integration` review and merge. - **18 are blocked by a single failing build check** - almost always pnpm-lock sync drift between the agent's working tree and CI. The fix is mechanical; the cost is that they cannot auto-merge. - **0 changes-requested** (none of these repos have formal review gates configured). - **51 awaiting first-pass Devin review.** The two PRs against `developers-digest-site` itself are the worst stuck - they fail four checks each (`analyze`, `check`, `lighthouse`, `typecheck`) because the marketing site has the strictest CI in the empire. That's by design and I am not going to soften it. ## The Pattern: Audit Once, Fix in Fanout, Document in Skills The thing worth extracting from this day is not any individual fix. It is the loop: 1. **Audit once.** A single 30-second `curl -P 10` sweep across all hosts produced a complete drift matrix. No app-by-app investigation, no spreadsheet maintenance. 2. **Fix in fanout.** Each row of the matrix becomes a templated PR job. Agents clone to `/tmp//` (in-place agents collide on branch switches), apply the same patch, push, open a private PR, tag Devin. One per repo. 3. **Document in skills.** Every recurring pattern from the day gets promoted into `~/.claude/skills/` so the next audit is faster and the next fanout has a tighter template. Today's session added entries for `dd-pr` (the branch → PR → tag-Devin convention) and the parallel-clone strategy. The key insight is that consistency across an app empire is not a one-time job. It is a *recurring drift problem*. The only durable answer is to run the audit weekly via cron and keep the fanout templates warm. ## What's Outstanding Two things did not get fixed today: - **GitHub Actions billing.** A handful of CI checks are queued behind an Actions usage cap on the org. Until that's resolved, even the CLEAN PRs can't auto-run their final checks. Migration to a higher tier is on tomorrow's list. - **Coolify dashboard work.** The seven down hosts all need triage in Coolify - some are 5xx (deploy broken, fixable via lockfile sync), some are 000 (DNS / TLS / image build). Each requires hands-on dashboard time. I will not be batching this; the failure modes are too varied. ## What This Cost The cost of this kind of day is mostly agent time, not human time. I spent about 90 minutes actively driving - writing the audit script, reviewing the drift matrix, queuing the fanouts, spot-checking Devin reviews. The agents did the rest in parallel. Three things made it tractable: - **One source of truth.** `apps-data.ts` on this site is the canonical list of every deployed app. Every audit script reads from it. - **Tight per-PR scope.** Each fanout PR touches one or two files. No PR ever combined "add favicon" with "fix Sentry" - that's how you get rejections. - **Honest skip allowed.** Agents that hit a repo with non-standard structure are allowed to skip with a written reason instead of forcing a broken PR. About 12% of the queued jobs ended up in the skip pile, which is fine. If you are running more than five deployed apps from the same starter, you already have this drift problem. The longer you wait to audit, the worse the matrix gets. Run the curl sweep this week.

219 PRs in One Day: A Parallel Agent Fan-Out Postmortem

Developers Digest — Wed, 06 May 2026 00:00:00 GMT

## The Setup I run a small empire: 35 apps under the developersdigest org, each one a separate repo, most of them deployed on Coolify, a few stragglers still on Replit and Vercel. Migrations across that many repos used to mean a week of context-switching. This week I tried something different: spawn one subagent per repo, fan out, let them work in parallel, then come back and review. The session shipped 219 pull requests in one day. Here is the honest breakdown - the patterns that survived contact with reality, the ones that exploded, and the fixes that turned chaos into a repeatable workflow. ## Why Parallel The work was embarrassingly parallel by nature. Same migration, 35 different codebases, no shared state. A sequential loop would have taken eight hours of agent time and probably twelve hours of me babysitting tool calls. A parallel fan-out is bounded by the slowest agent, not the sum of them. The pitch is simple: if your task decomposes into N independent units of work, the wall-clock time should be dominated by the longest unit, not N times the average. That is the whole shape of the speedup. Three sequential searches are slower than three parallel agents. Three hundred sequential migrations are catastrophically slower than three hundred parallel ones. ## Patterns That Worked **Tight scope per agent.** Every agent got one repo, one branch, one PR target. No agent was allowed to touch shared infra. No agent could decide its own scope. The prompt was a checklist, not a goal. When I gave agents room to interpret, they invented work - extra refactors, README rewrites, dependency bumps nobody asked for. When I gave them a checklist, they finished and stopped. **The honest-skip rule.** I baked into every prompt: *if this repo does not match the migration profile, return SKIPPED with a one-line reason and exit cleanly.* This was the single most useful pattern. Without it, agents will hallucinate work to look productive. With it, ~40 of the 200+ runs returned honest skips - repos already migrated, repos that were docs-only, repos with no deploy target. Those skips saved hours of cleanup. **`/tmp//` isolation.** The first thing I tried was running multiple agents against the same local checkout. Catastrophic. Branch switches collided, working trees got tangled, two agents committed to each other's branches. The fix: every agent clones fresh into `/tmp//`, works there, pushes, opens its PR, and never touches the canonical local copy. Disposable working directories are non-negotiable for parallel work. ## Patterns That Broke **Rogue `pkill` collisions.** A few agents had build steps that ran `pkill -f next` to clean up dev servers. With twenty agents running simultaneously, one agent's cleanup killed another agent's build mid-compile. Builds failed for reasons that had nothing to do with their code. I lost an hour chasing ghost failures before I traced it. **Disk fill.** Two hundred clones of medium-sized Next.js repos plus 200 `node_modules` installs blew through 60GB. Coolify started returning 500s on unrelated apps because the host disk was full. `docker builder prune -f` fixes this after the fact, but the better answer is to never let it happen. **False-empty remotes.** Several agents reported "nothing to commit, branch is clean" when in fact they had simply failed to detect modified files because they had `cd`'d into the wrong directory after a clone. The PR opened but contained zero diff. From the dispatch log it looked like a successful run. I caught these only by spot-checking PR diffs by hand. ## Fixes **Build-lock script.** A simple flock-based wrapper around any command that touches a shared resource. Builds serialize through the lock, everything else stays parallel. Crude but it works. **Fallback to local copies.** When a `/tmp//` clone failed for billing or network reasons, fall back to copying from a local cache directory rather than failing the run. Saved a dozen agents during a brief GitHub API blip. **Narrow filters.** Instead of "run this on every repo," I now generate the target list explicitly with a query - "repos with `nixpacks.toml` and no `coolify.yml`, modified in the last 90 days." Smaller, sharper target list, fewer wasted runs, fewer false-empty PRs. ## Outcome 219 pull requests opened. Maybe 70% of them are mergeable as-is. The rest need small edits - a wrong env var name, a stale port number, a missing health check. The bottleneck now is not agent capacity. It is human review bandwidth and, embarrassingly, a GitHub Actions billing cap I hit around PR 180. Two non-code lessons came out of this: 1. **Devin review is the new rate limit.** I tag @devin-ai-integration on every DD PR for a second-pass review before merge. With 200+ open PRs that queue is now the choke point. Parallelizing the agent does nothing if the reviewer is serial. 2. **GitHub billing scales with your agents.** I tripped a private-repo Actions minute cap I had never come close to before. Worth budgeting for if you plan to run anything like this regularly. ## The Skill Codification The whole recipe - the clone pattern, the honest-skip rule, the build lock, the PR-and-tag-Devin flow - is now a single skill called `replit-to-coolify`. I trigger it with one phrase and a target repo, and the same well-debugged prompt runs every time. That is the actual outcome of a session like this. Not the 219 PRs. The 219 PRs are the artifact. The skill is the asset. Next time I have a many-repos-one-change job, I do not have to re-derive the patterns. I run the skill, fan out, and review. The whole cycle from "I should migrate these" to "PRs are open" collapses from a week to an afternoon. If you are sitting on a portfolio of repos that need the same change, the leverage is real. Just budget for the disk, the billing, and the reviewer queue before you press go.

38 Apps in One Day: Migrating an Empire from Replit to Coolify

Developers Digest — Wed, 06 May 2026 00:00:00 GMT

## The Hook 38 apps. One day. Roughly 120 pull requests across the empire. By the time the dust settled, every Replit-hosted project under our org had a `migrate/coolify-clerk` PR sitting in review, pre-staged for one-click Coolify deploy. This is the candid version. What worked, what was a stub that did not need migrating, and what the recipe actually looks like when you repeat it 38 times in a day. ## Why We Moved Off Replit Replit was a great place to scaffold something at 1am. It is not where you want production infra to sit long-term. The reasons stacked up: - **Vendor lock-in on the runtime.** Replit's Nix layer, deployment targets, and proprietary databases meant every app carried a small but real "this only runs here" tax. Moving them was easier than continuing to pay it. - **Runtime quirks at scale.** Cold starts, opaque crash loops, and a control plane we did not own. When 38 apps are all using the same hosting layer, every quirk multiplies. - **No infra parity with the rest of our stack.** The serious DD apps already lived on Coolify (Hetzner) with Neon Postgres, Clerk auth, and Cloudflare DNS. Splitting hosting providers meant two debugging playbooks, two billing surfaces, two sets of secrets. - **Cost.** We were paying for always-on Replit deployments for apps that get a few hundred hits a week. A Hetzner box running 30+ containers is cheaper than the Replit equivalent by an order of magnitude. The decision was not "Replit bad." It was "one stack, one playbook, one bill." ## The Recipe Every migration followed the same shape, regardless of whether the app was Express or Next.js: **For Express + Vite + Drizzle apps:** 1. Strip Replit-specific files (`.replit`, `replit.nix`, runtime polyfills). 2. Add Clerk for auth, replacing whatever Replit Auth shim was in place. 3. Move the database to Neon Postgres, point Drizzle at the new connection string. 4. Wrap it in a single-container Dockerfile that builds the Vite frontend and serves it from Express. 5. Add `coolify.json` plus health check endpoint. **For Next.js + Prisma apps:** 1. Same Replit cleanup. 2. Clerk for auth. 3. Neon for the Postgres, Prisma migrations rerun against the new DB. 4. Single-stage Dockerfile using the standalone Next.js output. 5. Coolify config plus `/api/health`. The single-container constraint was deliberate. Coolify is happiest when an app is one container with one port. No sidecars, no multi-service compose files unless the app genuinely needs them. Most did not. ## The Honest Stats The 38-app number sounds impressive until you break it down: - **38 repos targeted.** Pulled from the org-wide list of anything tagged or known to have Replit deployment history. - **~16 were genuine app migrations.** Real code, real users, real database, real port to do. - **~9 were empty stubs.** Repos scaffolded during a brainstorm, never actually built. The migration agent correctly skipped these and filed an "empty stub, no action" report. - **~5 were monorepos.** A single repo containing 2 to 4 deployable apps. Each got its own `migrate/` branch with the apps split into separate Coolify services. - **~4 were false-empties.** Looked empty at first pass because the actual app lived in a subdirectory or behind a non-default branch. The agent flagged these for human review rather than guessing. - **~4 were already migrated.** Drift from a previous half-finished migration attempt. We closed those out and noted the existing deploy. Total PRs opened across all categories: roughly 120. That includes the migration PRs, follow-up cleanup PRs (lockfile sync, env var fixes, health check tweaks), and a handful of `chore: archive` PRs for repos that should not have existed in the first place. ## The Tooling The fan-out was the interesting part. The pipeline was three CLIs and one orchestrator: - **`gh` CLI** for everything GitHub. Listing org repos, cloning, branch creation, PR open, PR comment, tagging reviewers. Every agent used `gh` and only `gh`. - **`neonctl`** for spinning up Neon Postgres branches per app. New project, new connection string, dump it into the env file, done. - **Claude Code subagent fan-out** as the orchestrator. The parent session held a queue of 38 repos. It dispatched one subagent per repo, each cloning to its own `/tmp//` directory to avoid the in-place collision problem we have hit before with 5+ parallel agents on the same checkout. At peak, we had 8 to 10 subagents running concurrently. Each one followed the same `replit-to-coolify` skill: clone, audit, decide if migration is needed, apply the recipe or honest-skip, open a PR on a `migrate/coolify-clerk` branch, tag the reviewer, exit. The honest-skip rule was load-bearing. Without permission to skip, an agent will hallucinate work to fill the silence. With it, the empty stubs and false-empties got flagged correctly instead of receiving fake migration PRs. ## Ship Status Every PR is sitting in review right now, tagged `@devin-ai-integration` for the automated review pass. The standing rule held across all 120 PRs: branch, PR, tag Devin, never direct-push to main. Each migration PR is pre-staged for one-click Coolify deploy. The Dockerfile builds, the health check responds, the env vars are documented in the PR body. When Devin signs off and we merge, Coolify picks up the push and deploys. We are merging in batches rather than all at once. Five to ten apps per evening, watch the Coolify queue, fix anything that breaks the build (usually a `pnpm-lock.yaml` sync issue, the recurring failure mode), move to the next batch. ## What's Next Once everything is on Coolify: - **Decommission Replit deployments** after a 7-day grace period of dual-running. - **Standardize the observability layer.** Every app gets the same Sentry config and the same `/api/health` shape, so the empire dashboard can poll one endpoint per app and get a real signal. - **Consolidate Neon projects.** 38 separate Neon projects is too many. Group by tier and traffic so the free tier covers what it should and the paid tier covers what actually needs it. - **Write the `replit-to-coolify` skill into the standard scaffold.** New apps should never touch Replit again. The skill is now part of the default scaffold path. The interesting part of the day was not the migration itself. The recipe is boring once you have it. The interesting part was that 38 apps moved in a day because the orchestration was tight, the skip rule was honored, and every agent had the same playbook. That is the leverage. Not the agents. The playbook the agents share.

Claude Code Complete Course

Developers Digest — Wed, 06 May 2026 00:00:00 GMT

# Claude Code Complete Course This course is a full practical path from first install to team rollout. Every module uses official documentation and release sources, with direct links for verification. ## Official Sources Used Throughout - Claude Code overview: https://docs.anthropic.com/en/docs/claude-code/overview - Claude Code quickstart: https://docs.anthropic.com/en/docs/claude-code/quickstart - Claude Code tutorials: https://docs.anthropic.com/en/docs/claude-code/tutorials - Claude Code CLI reference: https://docs.anthropic.com/en/docs/claude-code/cli-reference - Claude Code settings: https://docs.anthropic.com/en/docs/claude-code/settings - Claude Code output styles: https://docs.anthropic.com/en/docs/claude-code/output-styles - Claude Code memory: https://docs.anthropic.com/en/docs/claude-code/memory - Claude Code MCP: https://docs.anthropic.com/en/docs/claude-code/mcp - Claude Code SDK MCP: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-mcp - Claude Code GitHub Actions: https://docs.anthropic.com/en/docs/claude-code/github-actions - Claude Code costs: https://docs.anthropic.com/en/docs/claude-code/costs - Claude Code security: https://docs.anthropic.com/en/docs/claude-code/security - Anthropic news and release updates: https://www.anthropic.com/news - Claude Code Action repository: https://github.com/anthropics/claude-code-action - GitHub Actions docs: https://docs.github.com/en/actions - GitHub Actions security hardening: https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions ## Course Outcomes By the end of this course, you will be able to: 1. Install and configure Claude Code for safe daily use. 2. Write deterministic prompts that reduce rework. 3. Run code changes with explicit review gates. 4. Integrate MCP tools with least privilege. 5. Automate PR workflows with GitHub Actions. 6. Track and optimize token costs. 7. Implement team governance for AI-assisted coding. ## Module 1 - Setup and First Run ### What You Learn - Installation flow and environment checks. - Authentication and first interactive session. - Basic command lifecycle and safe editing posture. ### Exercises 1. Install Claude Code and verify command availability. 2. Run your first session in a sandbox repository. 3. Perform one small refactor and inspect the diff. ### Screenshot Checklist - Terminal showing successful install. - First `claude` launch. - Login complete state. - First proposed diff with approval prompt. ### Primary Reading - Quickstart: https://docs.anthropic.com/en/docs/claude-code/quickstart - Overview: https://docs.anthropic.com/en/docs/claude-code/overview ## Module 2 - Prompt Engineering for Code Tasks ### What You Learn - Constraint-first prompting. - File scope limits and acceptance criteria. - Plan then patch then test pattern. ### Prompt Template ```text Objective: [exact outcome] Constraints: [files allowed, style rules, non-goals] Process: propose a plan first, then patch, then run tests Validation: list tests run and summarize risk ``` ### Exercises 1. Convert a vague prompt into a constrained prompt. 2. Compare results across three prompt variants. 3. Produce a reusable prompt template library for your team. ### Primary Reading - Tutorials: https://docs.anthropic.com/en/docs/claude-code/tutorials - Prompt engineering overview: https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview ## Module 3 - Diff Quality and Review Discipline ### What You Learn - Breaking large changes into staged commits. - Review-first behavior before applying broad edits. - Human review checklist for correctness and maintainability. ### Review Checklist - Does every changed file map to the requested scope? - Are tests added or updated where behavior changed? - Is error handling preserved or improved? - Is rollback straightforward if production issues appear? ### Primary Reading - CLI reference: https://docs.anthropic.com/en/docs/claude-code/cli-reference - Security docs: https://docs.anthropic.com/en/docs/claude-code/security ## Module 4 - Settings, Memory, and Output Control ### What You Learn - Configure output style by task type. - Use memory features for long-running workflows. - Reduce context noise during focused implementation. ### Exercises 1. Create two settings profiles: concise and teaching. 2. Run the same task with each profile and compare outcomes. 3. Document when each profile should be used. ### Primary Reading - Settings: https://docs.anthropic.com/en/docs/claude-code/settings - Output styles: https://docs.anthropic.com/en/docs/claude-code/output-styles - Memory: https://docs.anthropic.com/en/docs/claude-code/memory ## Module 5 - MCP Integration Basics ### What You Learn - MCP architecture and trust boundaries. - Connecting tools safely. - Diagnosing tool timeout and data-shape failures. ### Exercises 1. Configure one MCP server in a test project. 2. Execute one tool-assisted coding task. 3. Validate fallback behavior for tool failures. ### Primary Reading - MCP docs: https://docs.anthropic.com/en/docs/claude-code/mcp - SDK MCP: https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-mcp - MCP GitHub org: https://github.com/modelcontextprotocol ## Module 6 - MCP Advanced Workflows ### What You Learn - Multi-tool sequencing patterns. - Stable intermediate outputs. - Failure handling and retries. ### Exercises 1. Implement two-step tool workflow with validation between steps. 2. Add bounded retries and fallback handling. 3. Write an operational runbook for the workflow. ### Primary Reading - MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk - MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk ## Module 7 - GitHub Actions Integration ### What You Learn - Action workflow design for pull requests. - Permissions minimization. - Secret handling and protected branches. ### Exercises 1. Configure `anthropics/claude-code-action@v1` in a repo. 2. Trigger review workflow from PR comments. 3. Add timeout, concurrency, and permission limits. ### Primary Reading - Claude Code Actions docs: https://docs.anthropic.com/en/docs/claude-code/github-actions - Action repository: https://github.com/anthropics/claude-code-action - GitHub Actions docs: https://docs.github.com/en/actions - Security hardening: https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions ## Module 8 - Cost Engineering ### What You Learn - Cost drivers in coding sessions. - Task decomposition for lower token usage. - Repeatable cost benchmarking. ### Exercises 1. Run baseline task and record cost. 2. Apply scope and prompt optimizations. 3. Compare cost and quality before and after. ### Primary Reading - Costs docs: https://docs.anthropic.com/en/docs/claude-code/costs ## Module 9 - Security and Governance ### What You Learn - Risk tiers for AI-assisted changes. - Human review requirements by tier. - Sensitive data handling boundaries. ### Governance Policy Starter - Tier 1 low risk: docs and non-critical refactors. - Tier 2 medium risk: feature edits requiring full tests. - Tier 3 high risk: auth, billing, infra changes with mandatory senior review. ### Primary Reading - Security docs: https://docs.anthropic.com/en/docs/claude-code/security - Anthropic news for updates: https://www.anthropic.com/news ## Module 10 - Team Rollout Plan ### What You Learn - Pilot design and success metrics. - Change management for engineering teams. - Standard operating procedures for daily use. ### Rollout Framework 1. Week 1: two-engineer pilot. 2. Week 2: evaluate quality and cycle-time. 3. Week 3: expand to one full squad. 4. Week 4: publish org standards and templates. ## Module 11 - Production Incident Scenarios ### What You Learn - Detecting incorrect automated edits. - Rollback and remediation paths. - Communication templates for incident response. ### Exercises 1. Simulate flawed patch in staging. 2. Run rollback with audit notes. 3. Document root cause and prevention controls. ## Module 12 - Capstone ### Capstone Brief Build a full feature with this flow: 1. Define acceptance criteria. 2. Generate plan. 3. Apply staged changes. 4. Run tests and lint. 5. Submit PR with risk and rollback summary. 6. Run CI assistant checks and finalize review. ### Capstone Scoring - Correctness: 30 percent - Code quality: 20 percent - Test quality: 20 percent - Security and governance: 15 percent - Cost discipline: 15 percent ## Required Screenshots for Publication Capture these and add to your course assets folder: 1. Install command and success output. 2. First authentication flow complete state. 3. First plan response. 4. Approval prompt before patch. 5. Diff preview. 6. Test run output. 7. MCP configuration example. 8. MCP tool call result. 9. GitHub Actions YAML excerpt. 10. PR comment trigger example. 11. Action run summary. 12. Cost output comparison. 13. Security checklist file. 14. Capstone final PR summary. ## Author QA Checklist - Every claim includes at least one official link. - Every lesson includes a hands-on exercise. - Every module includes at least one screenshot requirement. - Every advanced module includes cost and risk notes. - Every workflow can be run in a clean repository from scratch. ## Suggested Publishing Plan for Developers Digest 1. Publish this complete guide first. 2. Split each module into individual course lessons in `/courses`. 3. Add one hero image for the course page at `/public/images/courses/`. 4. Add a companion blog post for each advanced module. 5. Link all assets from tutorials and guides index pages. ## Release Maintenance Cadence Before each cohort or major promotion: - Re-check all official docs and release pages. - Re-run every command shown in lessons. - Re-capture screenshots if UI or workflow changed. - Update lesson notes with dated verification.

Claude Code 2.1.128 Is an Ops Release, Not a Feature Drop

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Claude Code 2.1.128 does not look like a launch. That is the point. The interesting part of the [2.1.128 release notes](https://github.com/anthropics/claude-code/releases/tag/v2.1.128) is how much of the work is about agent operations: MCP visibility, worktree correctness, telemetry isolation, plugin packaging, permission persistence, and noisy reconnect behavior. For people treating [Claude Code](/blog/what-is-claude-code-complete-guide-2026) as a daily coding agent instead of a demo, this is the kind of release that matters. ## Quick verdict If you use MCP, worktrees, hooks, plugins, or OTEL-instrumented local commands, upgrade. This is the kind of maintenance release that prevents expensive agent sessions later. If you are still choosing between coding agents, start with [/compare](/compare) and the cost side of the decision at [/pricing](/pricing). ## The take Claude Code is moving from "agent that edits files" toward "agent runtime you can operate." The new release says `/mcp` now shows tool counts for connected servers and flags servers that connect with 0 tools. That sounds tiny until you debug a broken [MCP server](/blog/what-is-an-mcp-server-beginner-guide-2026) in a real project. A server that connects but exposes no useful tools is one of the worst failure modes because the agent appears integrated while silently losing capability. The release also reserves `workspace` as an MCP server name, summarizes reconnecting MCP tools by server prefix, and fixes MCP image results when structured content and content blocks are returned together. This is plumbing. It is also the difference between "MCP is cool" and "MCP is supportable." That pairs with the direction in [Claude Code hooks](/blog/claude-code-hooks-explained), [Claude Code subagents](/blog/claude-code-sub-agents), and [parallel agent merge discipline](/blog/parallel-coding-agents-merge-discipline): once agents touch real repos, observability becomes product functionality. ## The worktree fix is the sleeper The release note that jumped out: `EnterWorktree` now creates the new branch from local HEAD as documented, instead of `origin/`. That means unpushed local commits are no longer dropped when entering a new worktree session. If you use [Claude Code agent teams](/blog/claude-code-agent-teams-subagents-2026), this matters immediately. Parallel agents often start from the current local state, not from pristine remote main. If a worktree is created from the wrong base, the agent can produce a valid-looking patch that is missing the exact context it needed. This is the practical version of the argument in [long-running agents need harnesses](/blog/long-running-agents-need-harnesses). The agent is not just the model. It is the git base, working directory, permission layer, tool registry, and handoff log around the model. ## OTEL isolation is a real production concern Another small but important change: subprocesses such as Bash, hooks, MCP, and LSP no longer inherit `OTEL_*` environment variables from Claude Code. That prevents OTEL-instrumented apps run through the Bash tool from accidentally using the CLI's own OTLP endpoint. If you have ever run local traces while an agent is executing tests, this is not cosmetic. It prevents telemetry from becoming polluted or misrouted. The same theme shows up in [local OTEL traces for agents](/blog/dd-traces-local-otel) and [agent finops](/blog/400-dollar-overnight-bill-agent-finops): measurement is only useful when you know which process produced the span. ## The opposing view The fair critique is that these are not headline features. No new model capability. No giant context-window claim. No magic "agent does everything" demo. Some users will skip the changelog because the bullet list feels like maintenance. But maintenance is exactly what agent tools need now. The AI coding market has enough demos. The scarce thing is operational discipline: reliable worktrees, visible tool counts, quieter reconnects, clean telemetry, persistent permission choices, and predictable plugin loading. That is also why [skills need exit criteria](/blog/agent-skills-production-checklist). Teams are not blocked by a lack of agent ambition. They are blocked by missing control surfaces. ## What to do after upgrading If Claude Code is part of your daily workflow, this release suggests a short checklist: 1. Run `/mcp` and check every connected server has the expected tool count. 2. Rename any MCP server called `workspace`. 3. Test one worktree-based agent flow from a branch with unpushed local commits. 4. Confirm local test commands still emit OTEL traces to the endpoint you expect. 5. Review which Bash permission prompts should persist into `.claude/settings.local.json`. That is less exciting than installing a new model. It is also more likely to prevent a bad agent session. ## Frequently Asked Questions ### What changed in Claude Code 2.1.128? The release includes MCP tool-count visibility, `workspace` reserved as an MCP server name, cleaner MCP reconnect summaries, a worktree base fix for `EnterWorktree`, OTEL environment isolation for subprocesses, plugin archive support, and multiple terminal and permission fixes. ### Why does MCP tool count matter? It makes broken integrations easier to spot. If an MCP server connects but exposes 0 tools, the agent may appear connected while missing the capabilities you expected. ### Should teams upgrade immediately? If your workflow uses MCP, hooks, worktrees, plugins, or OTEL-instrumented local commands, yes. This is an operational reliability release more than a feature release. ### How does this relate to parallel agents? Parallel agents depend on correct worktree state and clean tool visibility. A wrong branch base or silent MCP failure can make a parallel agent produce a patch that looks valid but was built from the wrong context.

Codex Automations: Where Scheduled AI Agents Actually Help

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Codex automations are easy to misunderstand. The weak version is "schedule a prompt." That is useful, but not that interesting. The strong version is different: > Give an agent a repeatable workspace job, clear evidence sources, a reviewable output, and a safe schedule. That is where Codex becomes practical for engineering teams. OpenAI's [Codex Automations](https://openai.com/academy/codex-automations) guide says Codex can return on a schedule, do recurring work, and surface results for review. The examples are deliberately mundane: morning briefs, weekly reviews, checking missing information, summarizing recent activity, and recurring status updates. That mundanity is the point. The best automations do not replace judgment. They remove repeated context gathering. ## What Codex Automations Are Good For The sweet spot is recurring work with the same shape every time. Good examples: - daily repo brief from git history, issues, and open PRs - weekly QA sweep over known pages - stale docs check against recent code changes - dependency update summary - changelog draft from merged commits - SEO report from analytics and recent content - recurring "what changed while I was away" handoff - review-comment triage before a sprint planning block OpenAI's [Codex app announcement](https://openai.com/index/introducing-the-codex-app/) gives similar internal examples: daily issue triage, CI failure summaries, release briefs, and bug checks. That is a strong signal about intended use. Automations are not just for novelty reminders. They are for operational work that is annoying because it is repeated, not because it is intellectually hard. ## The Automation Test Before scheduling a Codex automation, ask five questions. ### 1. Does it have stable inputs? Bad: ```txt Tell me what matters. ``` Good: ```txt Inspect the last 24 hours of git commits, open GitHub PRs, QA.md, and SEO-DAILY.md. ``` Stable inputs make the task reproducible. If the input set changes every run, the output will drift. ### 2. Is the output reviewable in under two minutes? An automation should produce something you can scan quickly: - changed files - priority list - short report - draft PR description - markdown note - table of gaps - yes/no status with evidence If the output requires a long investigation to trust, the automation did not save much time. ### 3. Can the agent act safely? Some jobs should report only. Some can edit files. A few can open PRs. Almost none should push, merge, email, delete data, or spend money without explicit approval. The default should be: ```txt Report first. Draft changes only when low risk. Do not publish, send, push, merge, or delete. ``` That rule is boring. It is also what keeps scheduled agents from becoming scheduled incidents. ### 4. Is there a verification command? The best automations end with checks: - `pnpm lint` - `pnpm typecheck` - `pnpm build` - route smoke test - broken-link scan - screenshot check - data freshness check No verification means the automation is mostly a writer. Verification turns it into a worker. ### 5. Does it improve with memory? OpenAI notes that some automations can return to the same conversation and continue from existing context. That is valuable when the work has a running state: - a recurring SEO plan - an open migration - an issue queue - a content backlog - a weekly release rhythm If every run starts cold, it can still help. But the compounding value comes when Codex remembers what happened last time and avoids repeating the same shallow recommendation. ## The Best Engineering Automations ### Daily Repo Brief This is the first automation I would set up on almost any project. ```txt Every weekday morning, review the last 24 hours of git history, open PRs, failing checks, and QA.md. Produce a short repo brief with: 1. What changed 2. What is risky 3. What needs review 4. The next 3 actions Do not edit files unless I explicitly ask in this thread. ``` Why it works: - stable inputs - low risk - high context value - easy to review This is not glamorous, but it reduces the cost of re-entering a project. ### CI Failure Triage The automation: ```txt When scheduled, inspect recent failing checks, summarize the likely cause, link to the relevant logs, and propose the smallest fix. Do not modify code unless the fix is isolated and the failing test is clear. ``` Why it works: - CI has concrete evidence - logs are reviewable - the agent can compare failure text to recent diffs - the output saves immediate debugging time The trap is letting it guess. The prompt should require log links, command names, and the exact failing step. ### Stale Docs Sweep The automation: ```txt Every Friday, compare recent code changes against README.md, AGENTS.md, CLAUDE.md, docs, and content guides. Report docs that appear stale. Only edit docs when the code evidence is direct. ``` Why it works: - docs drift slowly - recent commits are a good signal - the task is narrow - the output is easy to review This is especially valuable in agent-heavy repos, where instructions are part of the product. ### SEO Compounding Pass The automation: ```txt Every morning, inspect analytics, recent content, SEO-DAILY.md, and QA.md. Pick the five highest-impact SEO improvements that are safe to complete today. Prefer internal links, metadata fixes, source freshness, comparison routing, and stale high-traffic pages. ``` Why it works: - analytics create a priority signal - content files are editable - verification is straightforward - improvements compound The key is avoiding volume theater. Five meaningful actions beat twenty generic internal links. ### Release Brief Draft The automation: ```txt Every Thursday, inspect merged commits since last release and draft a release brief. Group changes by user impact, include known risks, and list verification evidence. Do not publish. ``` Why it works: - merged commits are stable - release notes are repetitive - humans should still approve tone and priority This is a good example of Codex as an operator, not a decision maker. ## Where Automations Fail ### Vague ownership If nobody owns the output, it becomes noise. Bad: ```txt Check the project every day. ``` Better: ```txt Every day, update HANDOFF.md with missing video-to-blog coverage and list the top 3 gaps for review. ``` ### Too much autonomy Scheduled agents should not surprise you. Avoid: - auto-publishing public content - sending emails - changing billing settings - merging PRs - deleting data - making large refactors There are exceptions, but they need explicit trust, clear rollback, and narrow scope. ### No evidence trail Every automation should show what it inspected. Good output includes: - files read - commands run - external sources checked - analytics windows used - assumptions made - skipped actions and why Without that trail, you are reviewing vibes. ### Weak schedules Not every recurring job should run daily. Daily: - repo brief - analytics pulse - priority triage Weekly: - docs drift - release notes - dependency sweep - content backlog review Monthly: - pricing refresh - full SEO audit - architecture docs review - stale screenshot cleanup Wrong frequency turns useful automation into background clutter. ## A Good Codex Automation Prompt Template Use this: ```txt Purpose: Explain why this automation exists. Inputs: List exact files, dashboards, repos, issue filters, or docs to inspect. Actions: Describe what Codex should do every run. Boundaries: Say what it must not do without approval. Output: Specify the report, file edit, summary, PR draft, or checklist format. Verification: List commands, screenshots, links, or evidence required before it reports done. Memory: Tell it what to remember or compare against from prior runs. ``` That looks heavier than a casual prompt because scheduled work needs more discipline. A bad one-off prompt wastes a turn. A bad automation wastes attention every time it runs. ## How This Connects To `/goal` Codex automations and Codex `/goal` are related, but not identical. - Automations answer: **when should the agent run?** - Goals answer: **what persistent target should the agent keep working toward?** The strongest pattern is both: ```txt Every weekday, return to this SEO improvement goal. Review analytics, choose the highest-impact safe action, make the edit, run checks, update SEO-DAILY.md, and report what changed. ``` The automation provides cadence. The goal provides continuity. That is the move from "scheduled prompt" to "recurring agent workflow." ## Practical Takeaway Codex automations are most useful when they are: - specific - repeatable - evidence-driven - reviewable - bounded - verified Do not automate taste. Do not automate judgment. Automate context gathering, routine checks, safe edits, and report generation. That is where scheduled AI agents are already useful: not as autonomous executives, but as reliable operators for the boring work that makes engineering teams faster. ## Sources - OpenAI Academy: [Codex Automations](https://openai.com/academy/codex-automations) - OpenAI: [Introducing the Codex app](https://openai.com/index/introducing-the-codex-app/) - OpenAI: [Codex for almost everything](https://openai.com/index/codex-for-almost-everything/) - OpenAI Developers: [Codex changelog](https://developers.openai.com/codex/changelog) - OpenAI Developers: [Codex docs](https://developers.openai.com/codex/)

Codex Is Becoming a General-Purpose AI Agent, Not Just a Coding Tool

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Codex is still described as a coding agent, but that label is starting to undersell what the product is becoming. The old mental model was simple: > Codex edits code, runs tests, and opens pull requests. That is still true. But OpenAI's recent product direction points at something broader: Codex as a **general-purpose work agent** that happens to be strongest when the work has files, tools, verification steps, and repeatable outputs. That distinction matters. A chatbot answers. A coding assistant edits code. A general-purpose agent can move across apps, gather context, update artifacts, check its work, and come back later. That is the interesting version of Codex. ## The Official Signal OpenAI's [Codex for almost everything](https://openai.com/index/codex-for-almost-everything/) announcement is the clearest product signal so far. OpenAI says Codex can now operate your computer, use more tools and apps, generate images, remember preferences, learn from previous actions, and take on ongoing repeatable work. That is not just "better autocomplete." It is the shape of an agent workspace. The newer [OpenAI Academy overview of Codex](https://openai.com/academy/what-is-codex/) says the quiet part directly: Codex can be useful beyond software for tasks that require more than a single answer, including gathering information from multiple sources, creating and updating files, and producing documents, slides, and spreadsheets. So yes, code is still the home base. But the product boundary is expanding. ## What Makes Codex General-Purpose The important part is not that Codex can "do anything." It cannot. The useful framing is narrower: Codex is good for work that has **state, tools, artifacts, and review**. That includes: - reading a repo, notes, docs, emails, or dashboards - making changes across many files - using a browser to inspect a local app - generating product images or mockups from context - opening documents, spreadsheets, slides, and PDFs in a workspace - running repeatable tasks through automations - carrying context forward with memory and previous-thread continuation - coordinating work across plugins and app integrations Those are not all "coding" tasks. They are operational tasks. The reason Codex is good at them is the same reason it is good at code: it can interact with a workspace, not just produce a paragraph. ## The Best Non-Code Use Cases ### 1. Research To Artifact Codex is useful when the output is not an answer, but a file. Examples: - turn a pile of source links into a brief - convert notes into a product spec - make a slide outline from raw research - summarize a folder of PDFs into an internal memo - update a roadmap document from Linear, Slack, and repo state ChatGPT can help think through those tasks. Codex is better when you want the final result saved, structured, and checked against source material. ### 2. Browser-Based QA OpenAI's Codex update added an in-app browser and browser-oriented workflows for frontend design, apps, and games. That matters because a lot of product work fails at the visual or interactive layer. The useful prompt is not: ```txt Make this page better. ``` The useful prompt is: ```txt Open the local app, test the onboarding flow on desktop and mobile, capture what breaks, fix the highest-impact issues, and verify the flow works after the change. ``` That is not just coding. It is product QA with code edits as one possible action. ### 3. Repeatable Operator Work Automations are the most underrated part of the broader Codex direction. If Codex can wake up later with context, it becomes useful for work like: - checking stale docs - reviewing open PR comments - auditing broken links - refreshing SEO notes - checking dashboards and producing a priority list - following up on recurring operational tasks This is where Codex starts to look less like an IDE feature and more like a junior operator for recurring workflows. For the deeper setup pattern, read the [Codex automations playbook](/blog/codex-automations-recurring-engineering-work). The catch: the task needs a clear review loop. "Improve the business" is too vague. "Every weekday, inspect these five pages, fix broken internal links, run build, and report changed files" is usable. ### 4. File And Document Work The Codex app can preview more file types, including docs, spreadsheets, slides, PDFs, and richer artifacts. That unlocks a category of work that coding agents usually ignore: - clean up a spreadsheet - turn a technical memo into slides - inspect a PDF and extract action items - compare a document against a checklist - update a launch plan after a repo change This does not mean Codex replaces dedicated document tools. It means the agent can participate in the work where engineering, content, and operations overlap. ### 5. Image And Product Mockup Iteration OpenAI also added image generation into the Codex workflow. For developers, the interesting use case is not generic art. It is context-aware product imagery: - app mockups - visual concepts for features - blog hero images - game assets - lightweight design explorations tied to real code The best version of this is a loop: screenshot the current state, generate a visual direction, implement the UI, inspect it in browser, then iterate. That is a general-purpose creative workflow wrapped around a development environment. ## Where Codex Still Should Not Be Used Do not turn this into blind autopilot. Codex is still strongest when the task has: - clear inputs - a known workspace - explicit acceptance criteria - files or artifacts to update - commands or checks to run - a human review step It is weaker when the task depends on private judgment, ambiguous taste, unclear authority, or irreversible action. Bad Codex task: ```txt Handle my sponsorship pipeline. ``` Better Codex task: ```txt Read the last seven days of sponsorship emails, draft a priority list, identify replies that need review, and do not send anything. ``` The difference is control. General-purpose does not mean permissionless. ## How To Prompt Codex Like A General Agent The prompt format changes once you stop thinking of Codex as only a coding tool. Use this structure: ```txt Goal: Create a concise weekly content operations report. Context: Use the repo's recent git history, SEO-DAILY.md, QA.md, and current analytics report. Actions: Find the top 5 signals, update SEO-DAILY.md, and create a short next-actions section. Constraints: Do not publish new content. Do not touch unrelated files. No private sponsor details. Verification: Run lint or explain why no code checks apply. Report files changed. ``` That prompt gives Codex a job, boundaries, and evidence requirements. It is not asking for a vibe. It is delegating a workflow. ## The Real Category Shift The category is moving from "AI coding tool" to "agentic workspace." That does not make the coding angle less important. It makes code one artifact among many. A real software project includes PRs, docs, screenshots, QA notes, dashboards, deployment logs, customer feedback, specs, spreadsheets, and follow-up tasks. Codex is starting to sit across that whole surface. That is why the comparison with [Claude Code](/blog/codex-vs-claude-code-april-2026), [Cursor](/blog/cursor-vs-codex), and [GitHub Copilot](/blog/github-copilot-coding-agent-cli-2026) needs to widen. The question is not only "which model writes better code?" The better question is: > Which agent can safely move work forward across the tools where the work actually lives? For Codex, the answer is increasingly: more than code, but still with engineering-style constraints. ## Practical Takeaway Use Codex for non-code work when the task looks like a workflow: - gather context - update files - inspect outputs - run checks - leave a report - continue later if needed Do not use it as a magical executive assistant. Use it as a workspace agent with explicit scope. That is the useful version of "general purpose." Not a model that does everything. An agent that can keep moving through a real workspace until a reviewable artifact exists. ## Sources - OpenAI: [Codex for almost everything](https://openai.com/index/codex-for-almost-everything/) - OpenAI Academy: [What is Codex?](https://openai.com/academy/what-is-codex/) - OpenAI: [Codex product page](https://openai.com/codex) - OpenAI Developers: [Codex docs](https://developers.openai.com/codex/) - OpenAI Developers: [Codex changelog](https://developers.openai.com/codex/changelog)

Codex Loops: What Boris Cherny Gets Right About Managing Agent Work

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Boris Cherny's recent interview is worth watching because it names the thing most AI coding demos still hide: the future of agent work is not one perfect prompt. It is many supervised loops. In the interview, Boris describes a personal Claude Code setup that has moved far past "agent writes a diff." He talks about running multiple sessions, using sub-agents heavily, and leaning more and more on `/loop`: recurring agent jobs scheduled with cron. The examples are wonderfully boring: - babysit pull requests; - fix CI; - auto-rebase branches; - keep CI healthy; - cluster Twitter feedback every 30 minutes; - report back when a changing data stream needs attention. That is the useful part. The examples are not magical. They are the exact maintenance chores every engineering team already does poorly. This is also where Codex content should go next. [Codex automations](/blog/codex-automations-recurring-engineering-work), [Codex goals](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences), the [Codex GitHub Action](/blog/codex-sdk-vs-cli-github-action), and the [Codex cloud security playbook](/blog/openai-codex-cloud-security-playbook-2026) all point in the same direction: the winning agent workflow is a loop with boundaries, receipts, and escalation rules. ## The Big Shift: From Tasks to Loops The first AI coding workflow was a task: ```text Fix this bug. ``` The second workflow was a scoped task: ```text Fix the billing webhook validation. Only touch app/api/billing and lib/billing. Run pnpm test billing and pnpm typecheck. Return changed files, tests run, and risks. ``` The loop workflow is different: ```text Every 15 minutes, inspect open PRs labeled codex-watch. If CI is red for a deterministic reason, attempt one fix. If main moved, rebase once. If the same failure appears twice, stop and leave a concise report. Never push directly to main. ``` That is not just "task, repeated." It has a trigger, scope, action budget, stop condition, and reporting path. Those are the pieces that turn an agent from a clever assistant into a useful background process. ## Why Loops Beat One-Shot Agents One-shot agents are good at bounded edits. Loops are good at changing state. A PR changes after review comments land. CI changes after a dependency cache expires. A deployment changes after Coolify finishes building. User feedback changes every hour. A model eval changes after new examples arrive. These are not single-shot problems. They are state-monitoring problems. That is why Boris's examples land. PR babysitting and CI repair are high-value because they sit in the annoying gap between "the code is basically right" and "the work is actually merged." Codex is well positioned for this because the surface area is already there: - [Codex CLI](/blog/openai-codex-guide) for local scoped work; - [Codex GitHub Action](/blog/codex-sdk-vs-cli-github-action) for repo-triggered review and automation; - [Codex automations](/blog/codex-automations-recurring-engineering-work) for recurring checks and reports; - [Codex goals](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences) for longer-lived objectives; - browser verification for UI and deploy checks. The missing piece is not capability. It is loop design. ## The Loop Contract Every useful Codex loop should fit on one page. ```yaml name: pr-babysitter trigger: every: 15m scope: include: - pull_requests: labels: ["codex-watch"] exclude: - main permissions: repo: write-branch ci: read deploys: read budget: max_attempts_per_pr: 1 max_runtime_minutes: 20 max_files_changed: 8 stop: - same_failure_seen_twice - merge_conflict_requires_product_decision - tests_fail_after_one_fix report: destination: pr-comment fields: - summary - action_taken - tests_run - remaining_blocker ``` The contract matters because loops are powerful in the same way cron jobs are powerful: they keep running after the interesting part is over. Without a contract, a loop becomes background chaos. With a contract, it becomes a junior operations teammate that handles the boring parts and escalates the judgment calls. ## Four Codex Loops I Would Actually Run Start with loops that are safe, boring, and obviously reviewable. ### 1. PR Babysitter Trigger: every 15 minutes on PRs with a label. Job: - check CI; - rebase if main moved; - fix one deterministic failure; - summarize review comments; - report blockers. Stop if the same failure appears twice. Stop if the branch has merge conflicts that require a human decision. Stop if the fix touches files outside the declared scope. This is the cleanest Codex loop because it maps to GitHub's natural workflow. The output is a PR comment, a small branch commit, or a status report. ### 2. CI Health Loop Trigger: every 30 minutes on `main`. Job: - inspect the latest CI failures; - cluster failures by signature; - identify flakes vs deterministic failures; - open one issue or draft one fix branch. The important thing is not letting the agent quietly mutate production code. The first version should be report-only. Once the reports are useful, let it open a branch for the top deterministic failure. This pairs well with [long-running agent harnesses](/blog/long-running-agents-need-harnesses), because CI health is exactly where retry limits, tool logs, and receipts matter. ### 3. Deploy Verification Loop Trigger: after push to `main`, or every 10 minutes while a deploy is in progress. Job: - check deployment queue; - wait for active deploy to finish; - hit `/api/health`; - verify changed routes return 200; - confirm expected image paths or page text are present; - report live links. This is the loop I want for content automation. A blog post is not done when the commit lands. It is done when production returns 200 and the page references the expected hero image. For Codex, this should be a first-class recurring pattern because it is one of the easiest ways to turn agent work into visible shipped work. ### 4. Feedback Clustering Loop Trigger: every 30 or 60 minutes. Job: - pull feedback from GitHub issues, X, YouTube comments, Discord, Linear, or support channels; - cluster it by product area; - identify repeated complaints; - map each cluster to an existing post, guide, tool, or product gap. Boris mentioned clustering Twitter feedback. That is the exact pattern content teams should steal. It turns the outside world into a recurring editorial signal. For Developers Digest, this is how "go hard on Codex" becomes a system: - Codex question appears repeatedly; - loop clusters it; - agent checks whether a post already exists; - if not, a scoped draft gets proposed; - human picks the angle; - Codex ships the article and verifies production. ## The Failure Modes Loops fail differently from one-shot agents. ### They Keep Spending A one-shot agent fails and stops. A loop fails and comes back in 15 minutes. That can be good. It can also create the exact cost pattern from the [$400 overnight agent bill](/blog/400-dollar-overnight-bill-agent-finops): retry, inspect, edit, rerun, repeat. Every loop needs a hard budget: - max attempts per target; - max runtime; - max files changed; - max tool calls; - max spend; - max consecutive failures. ### They Hide Stale Assumptions A loop can keep acting on yesterday's plan after today's context changes. Fix: every loop run starts by refreshing the state it depends on. For PRs, fetch latest base and head. For CI, inspect the current run, not the last one cached in context. For deploys, ask production, not local build output. ### They Need Ownership If five loops can touch the same PR, you do not have automation. You have a race condition. Assign ownership: - one loop owns PR rebase; - one loop owns CI failure triage; - one loop owns content production verification; - one loop owns feedback clustering. Shared read access is fine. Shared write access should be rare. ### They Need Escalation The best loop is not the one that never asks for help. The best loop is the one that knows when it has hit a judgment boundary. Escalate when: - product behavior is ambiguous; - security permissions need widening; - the same failure repeats; - tests contradict each other; - a deploy is healthy but the page is wrong; - the loop would need to touch files outside scope. This is where agents become useful teammates instead of background scripts with model access. ## What Boris Gets Right The important insight in the interview is not that Boris runs an absurd number of agents. Most teams should not copy that directly. The important insight is that he is moving up a level of abstraction. He is not only asking agents to write code. He is asking agents to maintain workflows over time. That is the same shift Codex needs to own. Codex should not only answer: ```text Can you fix this bug? ``` It should answer: ```text Can you keep this PR moving until it is either merged or blocked by a human decision? ``` That second question is much more valuable. ## The Codex Version Here is the content and product thesis: Codex wins when it becomes the loop manager for engineering work. Not just the model that writes the code. Not just the CLI that edits files. The system that can: - start from a goal; - run scoped work; - verify with browser, tests, and production checks; - return on a schedule; - report what changed; - stop when judgment is required. That is the difference between agent assistance and agent operations. The next Codex content cluster should cover: - PR babysitting loops; - CI repair loops; - deploy verification loops; - feedback clustering loops; - cost caps for loops; - loop prompts and YAML contracts; - GitHub Action implementations; - when to use Codex automations vs CLI vs SDK. That cluster is more useful than another generic "what is Codex" post because it meets teams where they are: trying to turn agent output into shipped, reviewed, production-safe work. ## The Bigger Take Boris's loop-heavy workflow is a preview of where agentic coding is going. The headline is not "engineers will manage thousands of agents." The headline is smaller and more practical: Recurring engineering work is about to become agent-managed. The winning teams will not be the ones with the most agents. They will be the ones with the clearest loop contracts. For Codex, that is the content lane to own: how to design, run, verify, and stop the loops that keep software moving. ## FAQ ### What are agent loops? Agent loops are recurring AI workflows that inspect state, decide whether action is needed, act within a defined scope, and report results. They are useful for PR babysitting, CI repair, deploy verification, feedback clustering, and other changing-state engineering work. ### How is a loop different from a cron job? A cron job runs a fixed command on a schedule. An agent loop runs a recurring decision process: inspect the current state, choose an action, apply bounded changes, verify, and escalate if needed. ### How does this apply to Codex? Codex has the right surfaces for loops: CLI for local work, GitHub Action for repo events, automations for recurring checks, goals for longer-running objectives, and browser verification for production checks. The missing part is a clear loop contract. ### What is the safest Codex loop to start with? Start with a read-only PR review loop. Have Codex inspect pull requests with a label, summarize CI and review status, and post a concise comment. Add write access only after the signal is consistently useful. Sources: [Boris Cherny interview on YouTube](https://www.youtube.com/watch?v=SlGRN8jh2RI), [OpenAI Codex CLI docs](https://developers.openai.com/codex/cli), [OpenAI Codex SDK docs](https://developers.openai.com/codex/sdk), [openai/codex-action README](https://github.com/openai/codex-action), [OpenAI Codex changelog](https://developers.openai.com/codex/changelog).

Codex SDK vs CLI vs GitHub Action: Which Surface Should You Build On?

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Codex used to be easy to place in your head: install the CLI, run it in a repo, review the diff. That mental model is now too small. OpenAI has split Codex across several surfaces: app, web, IDE extension, CLI, GitHub integration, Slack, automations, and an SDK. The practical question for builders is not "should I use Codex?" It is **where should Codex live in my workflow?** This is the decision tree I would use: | Surface | Best job | Main risk | |---|---|---| | Codex CLI | Local, scoped engineering tasks | Human prompts stay informal | | Codex GitHub Action | CI-adjacent review, comments, generated artifacts | Over-permissioned runners | | Codex SDK | Productized agent features inside your own app | You now own the full UX and control plane | If you are new to the product, start with the [OpenAI Codex guide](/blog/openai-codex-guide). If you already understand Codex and want the current product direction, read the [April Codex changelog breakdown](/blog/codex-changelog-april-2026). This post is narrower: it is about choosing the right integration surface before you wire Codex into a team workflow. ## The Short Answer Use the **Codex CLI** when the human is still in the loop and the job starts from a terminal. Use the **Codex GitHub Action** when the job is triggered by repository events and the output belongs in GitHub: PR comments, review summaries, generated migration notes, failing-test explanations, release checks, or structured artifacts. Use the **Codex SDK** when Codex is not the product surface but the engine behind your own product: an internal code-mod assistant, a migration dashboard, an app-builder workflow, a customer-facing repo assistant, or a specialized review system with its own UI. The mistake is trying to make one surface do all three jobs. That is how teams end up with a brittle shell script that should have been an app, or a full SDK integration that should have been a 20-line GitHub Action. ## Codex CLI: Best for Human-Steered Work The CLI is still the most direct Codex surface. OpenAI's docs position it as the terminal pairing experience, and the command shape is exactly what you want for local repo work: ```bash codex exec "Add input validation to the billing webhook and update the tests." ``` The CLI is the right default when: - the developer is already in the repo; - local services matter; - the task needs quick back-and-forth; - you want to inspect files before approving changes; - the output should become a normal local diff. This is where Codex competes directly with [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Cursor agents, and other terminal-native coding tools. Codex's advantage is the OpenAI model stack, sandboxing defaults, and the growing app/CLI ecosystem around approvals, goals, browser verification, and worktrees. The CLI's weakness is that it inherits human prompt quality. If every task starts as "fix the thing," Codex will produce fuzzy work. The better pattern is to keep a tiny prompt template near your repo: ```text Goal: Constraints: - files/modules in scope - files/modules out of scope - command to verify - expected user-visible behavior Return: - summary - changed files - tests run - risks ``` That template is simple, but it converts Codex from "smart terminal" into a repeatable engineering loop. It also sets you up for the other surfaces later. ## Codex GitHub Action: Best for Repo Events The `openai/codex-action` repo gives teams a way to run Codex inside GitHub Actions while controlling privileges. The README is explicit about the architecture: the action installs the Codex CLI and configures a secure proxy to the Responses API. It also gives you knobs for sandbox mode, model, effort, output schema, output files, working directory, and safety strategy. This is the right surface when the trigger is already a GitHub event: - PR opened; - label added; - issue assigned; - nightly scheduled workflow; - release branch cut; - dependency update opened; - failing CI run needs explanation. The most useful first workflow is not "let Codex rewrite code automatically." Start with review output: 1. Check out the PR. 2. Fetch base and head refs. 3. Run Codex with a prompt constrained to the PR diff. 4. Post the final message as a PR comment. 5. Keep permissions read-only until the workflow earns trust. This is a better first step because review comments are easy to ignore, easy to compare, and easy to audit. Once the signal is good, you can graduate to generated artifacts or narrow autofix branches. ## The Safety Knob That Matters The GitHub Action docs include an unusually important input: `safety-strategy`. The default is `drop-sudo`, which removes sudo access before Codex runs on Linux and macOS runners. There are also `unprivileged-user`, `read-only`, and `unsafe` modes. That is not a small implementation detail. It is the difference between "agent can inspect this checkout" and "agent is running with broad runner privileges." For most teams, the starting point should be: ```yaml permissions: contents: read with: sandbox: read-only safety-strategy: drop-sudo ``` Then loosen only what the workflow proves it needs. This is the same security lesson from the [Codex cloud security playbook](/blog/openai-codex-cloud-security-playbook-2026): the agent's usefulness comes from access, and the risk comes from access. Good workflows make that access explicit. ## Codex SDK: Best for Productizing the Loop The SDK matters when Codex becomes part of your product rather than a tool your developers run. Examples: - a migration assistant that opens scoped modernization tasks; - a customer repo analyzer that produces implementation plans; - an internal platform that assigns small tasks to agents; - a code-review product with its own dashboard; - a teaching app that lets users run Codex against sandbox repos; - a maintenance workflow that turns errors into proposed fixes. If the UI, state model, permissions, billing, or reporting belong to your app, the SDK is the right surface. You get to design the control plane. You also have to design the control plane. That tradeoff is the whole point. With the CLI, OpenAI owns most of the product surface. With the GitHub Action, GitHub owns the event surface. With the SDK, you own the user experience, state transitions, permissions, observability, and failure handling. Do not pick the SDK because it sounds more serious. Pick it when your workflow has product requirements that the CLI and GitHub Action cannot express. ## A Practical Decision Matrix Here is the simplest way to decide. | Question | Pick | |---|---| | Does a human start the task from a terminal? | CLI | | Does a GitHub event start the task? | GitHub Action | | Does your app need to own the UX? | SDK | | Is the output a local diff? | CLI | | Is the output a PR comment or CI artifact? | GitHub Action | | Is the output a product workflow with users and state? | SDK | | Do you need a quick proof of concept? | CLI | | Do you need repeatable repo automation? | GitHub Action | | Do you need a differentiated product? | SDK | Most teams should move in this order: 1. CLI for manual proof. 2. GitHub Action for repeatable repo events. 3. SDK only after the workflow has proven value. That order keeps you from overbuilding. ## The Architecture Pattern The winning pattern is to keep the **task contract** portable across all three surfaces. Do not write one prompt for CLI, a different prompt for GitHub Actions, and a third prompt inside your SDK app. Write one task spec format: ```yaml goal: "Refactor the billing webhook validation" scope: include: - app/api/billing/** - lib/billing/** exclude: - migrations/** verification: commands: - pnpm test billing - pnpm typecheck output: format: - summary - changed_files - tests_run - risks ``` Then adapt the transport: - CLI reads the task spec from a local file. - GitHub Action reads it from `.github/codex/review.yml` or a prompt file. - SDK stores it as structured state in your app. This is how Codex content compounds. You are not building random prompts. You are designing a reusable task contract that can move from human use to automation to product. For the larger version of that idea, read [Codex automations for recurring engineering work](/blog/codex-automations-recurring-engineering-work) and [Codex `/goal` vs Claude Managed Outcomes](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences). ## What I Would Build First If I were adding Codex to a team today, I would not start with the SDK. I would ship three small things: 1. A repo-level `AGENTS.md` with exact project rules. 2. A `codex-tasks/` folder with reusable task specs. 3. A GitHub Action that runs Codex in read-only mode on PRs and posts concise review comments. Then I would watch three numbers: - how often Codex catches real issues before humans do; - how often humans ignore the comment; - how often the workflow needs write access. If the comments are useful, move from read-only review to generated patch branches. If the task specs become durable and reusable, consider the SDK. If developers keep manually running the same task locally, wrap it in the CLI first. The SDK should be the reward for a proven workflow, not the starting point. ## The Bigger Take Codex is turning into a multi-surface agent platform. That is good, but it creates a new design problem: teams have to decide which surface owns which job. The CLI is for developer-steered work. The GitHub Action is for repo-triggered automation. The SDK is for productized agent workflows. Use the smallest surface that preserves the control you need. Then keep the task contract portable so the workflow can grow without a rewrite. That is how you go hard on Codex without turning your engineering process into a pile of disconnected agent experiments. ## FAQ ### Should I start with the Codex SDK? Usually no. Start with the CLI or GitHub Action unless your app needs to own the user experience, state model, permissions, or reporting. The SDK is best after the workflow has proven value. ### Is openai/codex-action just the CLI in GitHub Actions? Broadly, yes. The action handles installing the Codex CLI and configuring a secure proxy to the Responses API, then exposes workflow inputs for prompt, model, effort, sandbox, output schema, output file, and safety strategy. ### What is the safest first GitHub Action workflow? Run Codex in read-only mode on pull requests and post a concise review comment. Keep repository permissions narrow and use the default `drop-sudo` safety strategy on Linux or macOS runners. ### When does the Codex SDK make sense? Use the SDK when Codex powers your own product or internal platform: migration dashboards, custom review systems, app-builder workflows, sandbox teaching tools, or maintenance agents with their own UI and state. Sources: [OpenAI Codex CLI docs](https://developers.openai.com/codex/cli), [OpenAI Codex SDK docs](https://developers.openai.com/codex/sdk), [openai/codex-action README](https://github.com/openai/codex-action), [OpenAI Codex changelog](https://developers.openai.com/codex/changelog).

Free Claude Code Is Really a Model Gateway Bet

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

The viral headline is "use Claude Code for free." The more interesting pattern is model gateways for coding agents. The [Free Claude Code repo](https://github.com/Alishahryar1/free-claude-code) describes itself as a drop-in Anthropic-compatible proxy for Claude Code. Its README lists backends including NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama, with per-model routing for Opus, Sonnet, Haiku, and fallback traffic. That is a bigger idea than a cost hack. It is a control plane between the coding agent and the model market. ## The take AI coding agents are becoming frontends. Model gateways are becoming infrastructure. Claude Code has the strongest workflow surface in many developer teams: terminal UX, project memory, tools, MCP, hooks, subagents, and worktree patterns. But some teams want provider flexibility, local routing, cheaper background work, or experiments with open models. Free Claude Code is one answer to that tension. Keep the agent UX. Swap the model backend. That overlaps with the argument in [self-hosting Claude Code on your own infra](/blog/self-hosting-claude-code-on-your-own-infra), [Aider vs Claude Code](/blog/aider-vs-claude-code-2026-update), and [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode). The coding-agent layer and the model layer are starting to separate. ## Why developers care Cost is the obvious reason. Long agent runs can burn through premium-model quota fast. If a proxy can route simple edits to a cheaper or local model and reserve frontier models for planning, debugging, and gnarly refactors, the economics change. But cost is not the only reason. Provider routing also gives teams: - local-model paths for sensitive code - fallback routes during provider outages - experiments with new coding models before native tools support them - separate budgets for planning, editing, and review - one place to log usage and failures That is why model gateways keep showing up around agent tools. Developers do not only want "the best model." They want the right model for the subtask. ## The security tradeoff The opposing view is important: a proxy between your coding agent and the model is now in the trust path. That proxy sees prompts, code context, tool calls, and sometimes secrets if your workflow is sloppy. It can also reshape requests and responses. That is powerful, but it means you should treat any model gateway like developer infrastructure, not a browser extension you installed on a whim. Before using a project like this on serious code, review: - where the proxy runs - what traffic it logs - how auth tokens are stored - whether it forwards secrets to third-party providers - how tool-use and reasoning blocks are translated - whether tests cover streaming and tool calls The Free Claude Code README says the proxy normalizes thinking blocks, tool calls, token usage metadata, and provider errors into the shape Claude Code expects. That is useful. It is also exactly the area where subtle bugs can become bad agent behavior. For more on the operational side, read [agent receipts](/blog/agent-swarms-need-receipts) and [the agent reliability cliff](/blog/the-agent-reliability-cliff). ## The quality tradeoff The other risk is capability mismatch. Claude Code's UX can make a weaker model feel more capable than it is. A local model may handle search-and-replace tasks well, then fail on multi-file architecture work. A cheap hosted model may stream quickly, then break tool-call formatting. A fallback route may save a run during an outage, but produce lower-quality patches. That does not make model gateways bad. It means routing policy should be explicit: | Task | Reasonable route | |---|---| | formatting, simple edits, docs cleanup | cheap or local model | | test repair with clear failure output | mid-tier coding model | | architecture refactor | frontier model | | security-sensitive repo exploration | local model when quality is enough | | final review before merge | strongest model plus human review | The practical question is not "can this run Claude Code for free?" It is "which parts of Claude Code work are safe to route away from the default model?" ## How I would use it I would not start by routing everything through a free model. I would start with a low-risk repo and three explicit lanes: 1. **Local lane:** docs, formatting, small mechanical edits. 2. **Budget lane:** first-pass test fixes and simple implementation tasks. 3. **Frontier lane:** planning, architecture, security-sensitive review, and final verification. Then I would log every run: prompt, model route, task type, tests run, whether the patch merged, and what human review fixed. Without that feedback loop, model routing becomes vibes. The real opportunity is not "free Claude Code." It is a team-owned gateway that makes coding-agent work measurable, cheaper where possible, and stricter where quality matters. ## Frequently Asked Questions ### What is Free Claude Code? Free Claude Code is an open-source Anthropic-compatible proxy that lets Claude Code talk to other backends, including NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama. ### Is Free Claude Code actually free? The repo can route to free or local providers, but "free" depends on the backend you choose. Some routes still require API keys, local hardware, or third-party quota. ### Is a Claude Code proxy safe for work code? Only if you trust and operate it like infrastructure. Review logging, auth, provider routing, secret handling, and tool-call translation before sending private code through any proxy. ### Who should use a model gateway for coding agents? Teams that need provider flexibility, lower costs, local-model experiments, or outage fallback paths. If you just want the simplest reliable Claude Code setup, the official path is still easier.

GPT Image 2 Prompt Libraries Are Becoming Production Infrastructure

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

The GPT Image 2 prompt-library wave looks like another pile of examples. It is more useful than that. The [OpenAI image-generation docs](https://developers.openai.com/api/docs/guides/image-generation) frame GPT Image as a programmable generation and editing system, with the Image API for single prompts and the Responses API for conversational image workflows. The current prompt-library repos are the missing practical layer on top: reusable recipes for layout, lighting, materials, product shots, diagrams, UI screens, and visual consistency. One current example, [awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2), describes itself as a prompt-as-code library with hundreds of reverse-engineered cases and industrial templates. The README says its goal is to turn scattered examples into structured protocols that agents and automation workflows can reuse. That is the right framing. ## The take Image prompts are becoming build artifacts. For a blog, product page, app directory, course hero, or social campaign, the prompt is not just creative prose. It is the spec that tells the image model what the asset should do, what it should avoid, what layout constraints matter, and how it fits the rest of the system. That is why a prompt library can be more valuable than another gallery. A gallery helps you admire outputs. A library helps you reproduce a direction. This is the same shift we are seeing with [agent skills](/blog/agent-skills-production-checklist), [skills as an agent operating system](/blog/skills-are-the-new-agent-operating-system), and [DESIGN.md for AI agents](/blog/design-md-for-ai-agents). The useful artifact is the reusable instruction layer. ## Why developers should care Developers are getting pulled into visual production. Landing pages need hero images. Docs need diagrams. Product launches need social cards. Internal tools need empty states and onboarding graphics. The image model can generate the pixels, but the team still needs repeatability. OpenAI's docs call out practical controls such as size, quality, output format, compression, and the distinction between the Image API and Responses API. They also note limitations around text rendering, consistency, and composition control. Those limitations are exactly why structured prompts matter. A production prompt should capture: - asset type - subject - scene and backdrop - composition - lighting - color constraints - material details - exact text rules - avoid list - validation criteria That is not artistic overkill. It is how you keep a site from turning into 30 unrelated stock images. ## The opposing view The fair criticism is that prompt libraries can become cargo cults. Copying a viral prompt rarely gives you a production asset. It gives you someone else's taste, aspect ratio, subject, and hidden assumptions. Worse, many prompt repos collect examples without source clarity, commercial-use clarity, or a real test harness. That matters. If you are shipping public brand assets, you need to know what is original, what was inspired by community content, and what rights or licenses apply. The awesome-gpt-image-2 README includes a disclaimer that it organizes public prompts and examples for learning and research, and tells users to obtain authorization from original rights holders before commercial use. That is the correct caution. Prompt libraries are reference material, not automatic rights clearance. ## What a useful prompt library looks like The best libraries will not just store prompts. They will store decisions. For each asset pattern, I want: 1. A short use case label. 2. A structured prompt schema. 3. Example outputs. 4. Known failure modes. 5. Model and quality settings. 6. Post-processing notes. 7. Brand constraints. 8. A checklist for accepting or rejecting the output. That is why I like prompt-as-code framing. It turns "make it look better" into a repeatable workflow an agent can run. For example, a Developers Digest blog hero prompt should say: cream background, tactile cards, black outlines, no readable generated text, no logos, no gradients, no emojis, restrained accent colors, and a concrete abstraction of the topic. That is a reusable visual contract, not a moodboard. ## How to use GPT Image 2 prompts in a real content workflow Start with one asset family, not the whole brand. For a technical blog, I would make four prompt templates: - article hero - comparison table visual - workflow diagram - social preview Then I would add a lightweight eval pass: - Does it explain the topic visually? - Does it match the brand system? - Is there any readable fake text? - Is the composition usable at mobile crop? - Is the file size acceptable? - Does the post reference the asset from a permanent repo path? That last one is boring, but critical. A generated image under a temporary path is not a published asset. Move it into the project, compress it, reference it in frontmatter, and verify the route. This is where prompt libraries become production infrastructure. They do not replace taste. They make taste easier to repeat. ## Frequently Asked Questions ### What is GPT Image 2? GPT Image 2 is OpenAI's current image-generation model available through image-generation workflows in the OpenAI API. The docs describe generation, editing, quality, size, format, and cost controls. ### Why are GPT Image 2 prompt libraries trending? Because strong image outputs are easier to repeat when prompts are structured into reusable schemas instead of one-off prose. Developers want templates for UI, infographics, product shots, brand visuals, and content assets. ### Can I use community prompt-library images commercially? Do not assume that. Treat community prompt libraries as references, then check the repo license, disclaimers, original sources, and rights for any examples you reuse. ### How should teams store image prompts? Store them near the content or design system, with the final asset path, model settings, known failure modes, and acceptance checklist. The prompt is part of the production artifact.

Karpathy's Loopy Era Is the Best Way to Understand Codex

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

Andrej Karpathy's "loopy era" interview with No Priors is one of the better explanations of the current AI coding shift because it does not frame the change as better autocomplete. The useful claim is sharper: the agent is now assumed. The new skill is designing loops that keep useful work moving without a human prompting every next step. That is exactly the lens I would use for Codex. If you still think of [OpenAI Codex](/blog/openai-codex-guide) as "a model that writes code," you will underuse it. The more interesting version is Codex as a control surface for agentic engineering: task specs, repo rules, parallel sessions, objective checks, budgets, escalation, and production verification. This also connects cleanly to Boris Cherny's loop-heavy workflow. Boris's `/loop` framing is about recurring engineering chores. Karpathy's loopy era is the larger principle underneath it: remove yourself from the prompt-next-step loop when the task has enough structure to run. For the existing Codex cluster, read this alongside [Codex loops and Boris Cherny](/blog/codex-loops-boris-cherny-agent-routines), [Codex `/goal` vs Claude managed outcomes](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences), and [Codex SDK vs CLI vs GitHub Action](/blog/codex-sdk-vs-cli-github-action). They are all pointing at the same workflow shape. ## The Karpathy Takeaway In the No Priors interview, Karpathy describes a personal workflow that moved from mostly hand-written code to mostly agent delegation. The important part is not the percentage. It is the unit of work. He is not talking about: - writing one function faster; - accepting a completion; - asking a chatbot for a snippet; - replacing an engineer with one giant prompt. He is talking about moving in **macro actions** over a repository. One agent researches. Another writes code. Another plans. Another explores a separate implementation path. The human steers, reviews, and designs the system around the agents. That is the jump from "vibe coding" to agentic engineering. The developer is less like a typist and more like an operator of parallel technical loops. This is also why [AI coding tool comparisons](/blog/ai-coding-tools-comparison-matrix-2026) that only score code generation miss the next decision point. The question is not just which model writes the best React component. It is which environment lets you safely run more useful loops. ## AutoResearch Is the Cleanest Example Karpathy's AutoResearch example is so useful because it has the ingredients that make loops work: ```text objective + metric + boundary + worker loop + result review ``` He describes setting up a research loop where agents try experiments, evaluate objective metrics, and continue without waiting for him to inspect every intermediate result. The goal is to maximize useful token throughput while removing the human as the bottleneck. That sounds abstract until you map it to software: | AutoResearch primitive | Software engineering version | |---|---| | Objective | Improve this benchmark, fix this failing path, reduce this latency | | Metric | Test pass rate, benchmark score, bundle size, route 200, typecheck | | Boundary | Files in scope, commands allowed, time budget, permission model | | Worker loop | Codex task, GitHub Action, CLI session, automation | | Result review | PR diff, logs, eval report, deploy check, human approval | This is why Codex is interesting right now. It already lives close to the software loop. It can read repo instructions, edit files, run commands, review diffs, and report what changed. With the [Codex GitHub Action](/blog/codex-sdk-vs-cli-github-action), the loop can also be attached to pull request events. With [Codex automations](/blog/codex-automations-recurring-engineering-work), the same pattern can become recurring work instead of one-off delegation. The point is not that Codex magically solves engineering. The point is that Codex is one of the more natural places to formalize the loop. ## The Loop Contract Matters More Than the Prompt The weak version of agentic engineering is: ```text Make the app better. ``` The stronger version is: ```yaml goal: "Reduce checkout route cold-start time by 20 percent" scope: include: - app/checkout/** - lib/payments/** exclude: - migrations/** - auth/** metric: command: "pnpm bench checkout" success: "p95 improves by at least 20 percent and tests pass" budget: max_runtime_minutes: 40 max_files_changed: 8 max_attempts: 2 stop: - metric_cannot_be_reproduced - same_failure_twice - needs_product_decision report: include: - changed_files - commands_run - before_after_metric - remaining_risks ``` That contract is the practical translation of Karpathy's loopy era into Codex work. It gives the agent enough room to continue. It gives the human enough structure to review. It gives the workflow a stopping point. Most importantly, it makes the loop portable. The same contract can start in the [Codex CLI](/blog/openai-codex-guide), move into GitHub Actions, and eventually become a productized workflow through an SDK. This is the real content lane for Codex: not "here is a clever prompt," but "here is the smallest reliable loop contract for a real engineering job." ## Where Codex Fits Codex has three especially useful roles in this loopy model. ### 1. The Local Loop The local loop is still human-steered. You run Codex from a repo, give it a narrow target, inspect the diff, and decide what happens next. This is where Codex competes with [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Aider, Cursor agents, and other terminal or IDE coding tools. It is also where the loop contract can stay lightweight: ```text Fix the failing tests in lib/billing. Only touch lib/billing and tests/billing. Run pnpm test billing and pnpm typecheck. Stop after one implementation path if the failure is ambiguous. ``` The local loop is best for high-context work where the developer is actively supervising. It is not the highest-leverage loop, but it is the safest place to learn how Codex behaves in your repo. ### 2. The GitHub Loop The GitHub loop is event-driven. A PR opens. A label is added. CI fails. A nightly schedule fires. Codex comments, reviews, drafts a patch, or produces an artifact. This is where the [Codex GitHub Action](/blog/codex-sdk-vs-cli-github-action) becomes more than a convenience wrapper. GitHub already has the state machine: - issues; - pull requests; - checks; - labels; - branches; - comments; - required reviews. Codex can sit inside that state machine if the permissions are narrow and the output is inspectable. Start read-only. Let it summarize failures, review diffs, and propose next actions. Only widen write access after the comments are consistently useful. That is the difference between agent automation and an overpowered CI job. ### 3. The Recurring Loop The recurring loop is the closest to Karpathy's point. It does not wait for a human prompt. It wakes up, refreshes state, checks whether useful work exists, acts inside a boundary, and reports. Examples: - watch PRs with a `codex-watch` label; - retry one deterministic CI failure; - verify deploys after `main` changes; - cluster repeated product feedback; - scan docs for drift against the current API; - create a daily content brief from new Codex changelog items. This is also where the [long-running agent harness](/blog/long-running-agents-need-harnesses) matters. A recurring loop without receipts is just an expensive cron job with model access. A recurring loop with logs, budgets, stop conditions, and escalation is an engineering system. ## The Opposing View Is Right About One Thing The skeptical view is not "agents are useless." The better skeptical view is that many loops are fake autonomy. Karpathy says the caveat clearly: this works best when the objective metric is easy to evaluate. If you cannot evaluate the result, you cannot safely automate the loop. That is a major limitation. Codex loops are good at: - fixing deterministic tests; - reducing benchmark numbers; - producing structured reports; - rebasing and summarizing; - verifying route health; - checking docs against source files; - comparing before and after outputs. Codex loops are weaker at: - ambiguous product taste; - visual design without screenshots and rubrics; - architecture decisions with hidden business constraints; - security work without narrow permissions; - content judgment without an editorial bar; - anything where "better" is not measurable enough. This is why [debugging agent workflows](/blog/debug-ai-agent-workflows) and [agent architecture](/blog/agent-architecture-multi-step-ai-workflows) are not side topics. They are the infrastructure around the loop. Once the agent can continue without you, failures become harder to see and more expensive to ignore. ## The Better Codex Workflow If I were setting up a Codex-heavy repo after watching the Karpathy interview, I would do five things. ### 1. Write `AGENTS.md` Like a Runtime Contract Do not treat repo instructions as polite preferences. Treat them as the first layer of the loop contract. Include: - commands to verify changes; - files that are off-limits; - deploy verification rules; - content style constraints; - security boundaries; - escalation triggers; - what "done" means. For a deeper version of that, see the [Codex macOS certificate runbook](/blog/openai-codex-macos-certificate-update-runbook). The useful part is not the certificate topic. It is the operational shape: exact commands, exact checks, and exact recovery paths. ### 2. Keep a Folder of Task Specs Create a `codex-tasks/` folder with reusable loop contracts: ```text codex-tasks/ fix-ci.yml verify-deploy.yml review-pr.yml update-blog-seo.yml refresh-docs.yml ``` Each file should name the trigger, scope, verification command, budget, stop conditions, and report format. This is how you move from improvisation to repeatability. It also makes Codex easier to compare against Claude Code or Cursor because you are comparing the same task contract, not vibes. ### 3. Split Parallel Work by Ownership Karpathy's macro-action point only works when tasks do not collide. Good split: - agent 1 owns `app/billing/**`; - agent 2 owns `tests/billing/**`; - agent 3 owns documentation; - agent 4 reviews the final diff. Bad split: - four agents all "make billing better." Parallel agents multiply throughput only when ownership is explicit. Otherwise they multiply merge conflicts and review load. ### 4. Make Metrics Boring The best loop metrics are not fancy: - `pnpm typecheck` passes; - `pnpm test billing` passes; - route returns `200`; - benchmark improves by a named threshold; - generated page includes the expected hero image; - no files outside scope changed; - no new lint errors; - production health count increments. This is why Codex is a good fit for engineering loops. Software has many cheap objective checks. Use them before asking the model to judge its own work. ### 5. Escalate Early The loop should stop sooner than your ego wants. Stop when: - the same failure appears twice; - the fix requires a product decision; - the agent wants broader permissions; - the task crosses ownership boundaries; - the metric is noisy; - the diff grows beyond reviewable size; - production behavior disagrees with local output. This is the part many agent demos skip. The future is not an agent that never asks for help. The future is an agent that knows exactly when it has crossed from execution into judgment. ## The Takeaway Karpathy's loopy era is not a slogan about agents getting smarter. It is a workflow claim: > The leverage comes from arranging work so agents can continue against metrics and boundaries while humans stop being the next-step bottleneck. Codex makes that concrete for software teams. The best Codex workflows will not be the longest prompts. They will be the cleanest loops: - one objective; - one owner; - one metric; - one boundary; - one budget; - one report path; - one escalation rule. That is how Codex moves from "AI coding tool" to agentic engineering infrastructure. ## Sources - No Priors, "Skill Issue: Andrej Karpathy on Code Agents, AutoResearch, and the Loopy Era of AI": https://www.youtube.com/watch?v=kwSVtQ7dziU - Karpathy's AutoResearch repository: https://github.com/karpathy/auto-research - OpenAI Codex docs: https://developers.openai.com/codex/ - OpenAI Codex CLI slash commands: https://developers.openai.com/codex/cli/slash-commands/ - OpenAI Codex changelog: https://developers.openai.com/codex/changelog/ - `openai/codex-action` repository: https://github.com/openai/codex-action

OpenAI's Codex Mac Certificate Deadline Is a Runbook Test

Developers Digest — Tue, 05 May 2026 00:00:00 GMT

OpenAI's latest macOS security notice looks, at first glance, like a normal "please update your app" banner. It is more useful than that. The May 8, 2026 deadline is a practical runbook test for every team that now treats AI coding tools as part of the developer workstation. The short version: OpenAI says a GitHub Actions workflow used in its macOS app-signing process downloaded and executed a malicious Axios package during the March 31, 2026 supply-chain incident. The workflow had access to certificate and notarization material used for ChatGPT Desktop, Codex, Codex CLI, and Atlas. OpenAI says it found no evidence that user data, internal systems, intellectual property, published software, or the certificate itself were compromised, but it is rotating the certificate anyway. That is the right boring move. Treat the material as exposed, rotate it, ship new builds, and force the old line to die on a calendar date. For Developers Digest readers, the interesting part is not "Axios was compromised." The interesting part is what this says about [Codex](/blog/openai-codex-guide), [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Cursor, Copilot, and every other agent that now sits close to source code, terminals, secrets, browsers, and internal repos. The agent is not just an app. It is a privileged developer surface. ## What Actually Changes on May 8 OpenAI says macOS users need to update by **May 8, 2026**. After that date, older macOS builds signed with the previous certificate will no longer receive updates or support and may stop functioning. The first versions signed with the updated certificate are: | Product | Earliest supported version | |---|---:| | ChatGPT Desktop | `1.2026.051` | | Codex App | `26.406.40811` | | Codex CLI | `0.119.0` | | Atlas | `1.2026.84.2` | This does not affect iOS, Android, Linux, Windows, or web versions according to OpenAI. It is specifically about macOS app signing and notarization. The right user action is simple: update through the in-app updater or official OpenAI download pages. Do not install OpenAI, ChatGPT, Codex, or Atlas builds from email links, ads, file-sharing links, random mirrors, or third-party download pages. The right team action is slightly broader: treat this as a drill. ## Why This Matters for AI Coding Teams Classic developer-tool updates were annoying but usually narrow. Your editor updated. Your terminal updated. Your package manager updated. You checked that it still launched and moved on. AI coding tools have a larger blast radius. A local agent can read files, edit code, run shell commands, call MCP servers, use browser sessions, and sometimes touch cloud runners. That does not make the tools bad. It means they deserve the same operational treatment you would give any privileged engineering surface. If you already read [the Codex April changelog](/blog/codex-changelog-april-2026), this direction is obvious. Codex is becoming more stateful, more integrated, and more capable. That is useful. It also means update hygiene becomes part of agent governance. The mistake is turning this into panic. OpenAI's notice is careful: it says there is no evidence of user-data compromise, software alteration, or misuse of the signing material. The better take is operational: this is what mature incident response around an AI developer tool should look like, and it gives teams a concrete checklist to copy. ## The Runbook I Would Use For solo developers, update the apps and move on. For teams, write the one-page runbook now. 1. Inventory every OpenAI macOS surface in use: ChatGPT Desktop, Codex App, Codex CLI, Atlas. 2. Confirm every Mac is on or above the minimum versions OpenAI listed. 3. Document the official update paths your team accepts. 4. Block installs from third-party mirrors, email links, shared zip files, and ad-driven download pages. 5. Add AI coding tools to your normal endpoint-management inventory. 6. Capture which repos, MCP servers, terminal permissions, and cloud accounts each tool can reach. 7. Keep one "known-good rollback" note, but do not pin to builds that will lose signing support. The key is step 6. Version numbers are table stakes. Permission mapping is the real maturity test. If a developer's Codex app can reach production repos, GitHub tokens, local `.env` files, and browser sessions, you need to know that before the next incident. This is the same lesson behind [the agent reliability cliff](/blog/the-agent-reliability-cliff): serious agent workflows fail at the surrounding control loop before they fail at model intelligence. ## The Opposing View: Is This Just Update Theater? There is a reasonable skeptical take here: OpenAI says it found no evidence that the certificate was exfiltrated or misused. It also says published software was not modified. So why make everyone update? Because signing material is not a normal secret. The whole point of a signing certificate is that the operating system and the user can trust that an app came from the named developer. If there is credible exposure in the signing pipeline, the clean answer is rotation. Waiting for public misuse would be worse. The more interesting critique is that this still depends on users and teams doing the boring part. A company can rotate certificates, publish clean builds, and warn users. If a team has no inventory of AI desktop tools, no version baseline, and no trusted download policy, it still has a gap. That gap is not specific to OpenAI. It applies to every agent tool that ships fast and sits inside the developer loop. ## What Tool Builders Should Copy OpenAI's post is useful because it names concrete remediation steps, not just vague reassurance. The good pattern: - explain the affected workflow; - state which products are in scope; - give exact minimum versions; - name the cutoff date; - say what was and was not found; - give safe download paths; - explain why revocation is staged instead of immediate. That is the template AI developer-tool companies should use. The best security post is not the one that sounds most dramatic. It is the one that lets a team close tickets without guessing. This is also where [skills as an agent operating system](/blog/skills-are-the-new-agent-operating-system) becomes more than a productivity pattern. If your organization uses agent skills, MCP configs, hooks, or local runbooks, the security update process should live there too. The next time a certificate rotation, OAuth scope change, or plugin revocation lands, your agent should know the team's exact update checklist. ## A Practical Codex Check For Codex CLI users on macOS, the minimum supported version after the certificate rotation is `0.119.0`. If your team installs Codex through the official docs, the check should be simple: ```bash codex --version ``` Then update through the official route documented by OpenAI. If your team wraps Codex in a dotfiles repo, bootstrap script, MDM profile, or devcontainer setup, update that source of truth too. Otherwise the same outdated version comes back the next time someone rebuilds a laptop. For the Codex desktop app, open the app and use the built-in update path or download from OpenAI's official page. Treat random "fixed" installers as hostile by default. ## The Bigger Take The AI coding stack is crossing a line from "tools developers try" into "infrastructure developers depend on." That changes the maintenance model. The useful response is not to avoid Codex, Claude Code, or local agents. The useful response is to operate them like real engineering systems: - pinned install sources; - known version baselines; - permission maps; - endpoint inventory; - update deadlines; - post-incident verification. That is less exciting than a new model benchmark. It matters more. The May 8 Codex and ChatGPT macOS deadline is a small event if you update one laptop. It is a larger signal if you run an engineering team: AI developer tools now deserve the same boring operational discipline as package managers, CI credentials, browser profiles, and deploy keys. ## FAQ ### Do I need to update Codex CLI on macOS? Yes. OpenAI lists `Codex CLI 0.119.0` as the earliest version signed with the updated certificate. On May 8, 2026, older macOS builds signed with the previous certificate will no longer receive support and may stop functioning. ### Was OpenAI user data compromised? OpenAI says it found no evidence that user data, products, internal systems, intellectual property, published software, or passwords/API keys were compromised. The certificate rotation is a precaution after exposure in the macOS app-signing workflow. ### Does this affect Windows or Linux Codex users? OpenAI says the issue only affects macOS apps. It does not affect iOS, Android, Linux, Windows, or web versions. ### Where should I download Codex updates? Use the in-app updater or official OpenAI download/docs links. Avoid installers sent through email, messages, ads, file-sharing links, mirrors, or third-party download sites. Sources: [OpenAI's Axios developer tool compromise response](https://openai.com/index/axios-developer-tool-compromise/), [Axios coverage of the OpenAI macOS signing incident](https://www.axios.com/2026/04/11/openai-axios-mac-cyberattack), [OpenAI Codex CLI docs](https://developers.openai.com/codex/cli).

Agent Skills Need Exit Criteria, Not More Prompt Lore

Developers Digest — Mon, 04 May 2026 00:00:00 GMT

The interesting part of [Addy Osmani's `agent-skills` repo](https://github.com/addyosmani/agent-skills) is not that it gives AI coding agents more markdown to read. The interesting part is that it treats senior engineering judgment as a reusable artifact. That is why the repo moved fast through the AI developer crowd. It packages production concerns like testing, accessibility, performance, code review, debugging, and migration work into skill files that can be dropped into tools such as Claude Code, Cursor, and Antigravity. The repo description is blunt: "Production-grade engineering skills for AI coding agents." That framing matters because the next phase of AI coding is not "write a better prompt." It is "make the agent inherit the team's definition of done." ## The take Skills are only useful when they contain exit criteria. A weak skill says: > Write better React components. A useful skill says: > Before finishing, run the local checks, verify the responsive states, preserve existing user edits, avoid new dependencies unless justified, and report what was not verified. That second version is closer to a production checklist than a prompt. It gives the agent a way to stop, inspect its own work, and produce a handoff that a human can review. That is the same reason [Claude Code skills are becoming a real workflow layer](/blog/skills-are-how-agents-learn-the-job), and why [skills beat prompts for coding agents](/blog/why-skills-beat-prompts-for-coding-agents-2026). The durable part is not the prose. It is the repeated operating procedure. ## Why developers are paying attention The repo is useful because it meets agents at the exact place they fail: judgment transfer. Most AI coding failures are not syntax failures anymore. They are taste, scope, verification, and integration failures. The agent can write the component, but it may not know the local design system. It can add tests, but it may test the wrong behavior. It can refactor the module, but it may erase an edge case the team learned the hard way. A skill can encode those constraints in a way that survives across sessions. That is different from a one-off instruction. A one-off prompt is a sticky note. A skill is closer to a small operating manual. ## The opposing view The fair criticism is that skills can become another pile of stale docs. If every team ships a 4,000-line skill pack, agents will skim, misapply, or ignore the important bits. Worse, bloated skills can make the agent sound more confident without making it more correct. That is the trap. Skills should not become a second codebase of aspirational process. Good skills are short, specific, and tied to observable behavior: - Which files or commands matter - What the agent must check before finishing - What it should never change casually - What evidence it should return - When it should stop and ask That is also why [long-running agents need harnesses, not hope](/blog/long-running-agents-need-harnesses). The skill is the instruction layer. The harness is the runtime layer. You need both if the work matters. ## What to copy from the repo The repo is best treated as a menu, not a template. Do not copy every skill into your project. Start with the recurring failures you already see: 1. Agents change too much. 2. Agents forget verification. 3. Agents ignore design constraints. 4. Agents lose context between sessions. 5. Agents produce vague final reports. Then write one skill per repeated failure. For example, a frontend repo does not need a generic "build nice UI" skill. It needs a design-system skill that says which tokens, components, breakpoints, and visual checks count as done. That pairs well with a project-level design contract like [`DESIGN.md`](https://github.com/google-labs-code/design.md), which gives agents a persistent way to understand a visual identity. For backend work, the useful skill is usually not "write APIs." It is "when changing this endpoint, update the schema, migration, tests, docs, and client types in the same change." ## How I would use it I would start with three production skills: **Review receipt skill.** Every agent change must report files changed, commands run, commands not run, and risks left open. This is the human review surface. **Scope discipline skill.** The agent must preserve unrelated local changes, avoid broad refactors, and explain why any new abstraction exists. **Verification ladder skill.** The agent starts with cheap checks, escalates to build or browser QA when the change touches user-facing behavior, and reports the exact result. Those three skills solve more real problems than a giant library of framework-specific tips. They also compose with [Claude Code subagents](/blog/claude-code-sub-agents), [multi-agent coordination](/blog/how-to-coordinate-multiple-ai-agents), and [agent replays](/blog/agent-replays-with-tracetrail). When multiple agents are working at once, the skill is how you make their handoffs consistent. ## The practical bottom line Agent skills are becoming the new team playbook. The best ones do not teach the model to code. The model already knows enough about code. They teach the model how your team decides a change is finished. That is the shift Addy's repo makes visible. The winning teams will not have the longest prompts. They will have the clearest operating rules, the smallest reusable skills, and the strongest verification habits. Sources: [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills), [google-labs-code/design.md](https://github.com/google-labs-code/design.md), [Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills). ## Frequently Asked Questions ### What are agent skills for AI coding tools? Agent skills are reusable markdown files that teach AI coding assistants like Claude Code and Cursor how to approach specific types of work. Unlike one-off prompts, skills persist across sessions and encode team-specific constraints, verification steps, and exit criteria. They turn senior engineering judgment into a repeatable artifact that agents can reference whenever they tackle similar tasks. ### What is the difference between a skill and a prompt? A prompt is a single instruction for one task. A skill is a reusable operating procedure that loads automatically when relevant work arises. Prompts are like sticky notes - used once and discarded. Skills are like a small operating manual that the agent consults every time it handles a specific category of work. Skills survive across sessions and apply consistently. ### What makes Addy Osmani's agent-skills repo useful? The repo packages production engineering concerns - testing, accessibility, performance, code review, debugging, and migration - into skill files ready for Claude Code, Cursor, and Antigravity. The value is not the prose itself but the exit criteria embedded in each skill. They define what "done" means for each task type, which is exactly where agents fail without guidance. ### How many skills should a project have? Start small. One skill per repeated failure pattern is the right ratio. A giant library of framework-specific tips will bloat context and make agents skim or misapply the important bits. Focus on the three to five recurring problems your team actually sees: agents changing too much, skipping verification, ignoring design constraints, losing context, or producing vague reports. ### What should a good agent skill contain? A useful skill is short, specific, and tied to observable behavior. It should include which files or commands matter, what the agent must check before finishing, what it should never change casually, what evidence it should return, and when it should stop and ask. Exit criteria are the core - without them, the skill is just more prose. ### Can I use skills with Claude Code and Cursor? Yes. Both tools support skill files in markdown format. Claude Code reads skills from a designated directory and auto-loads them based on trigger conditions. Cursor supports similar files through its rules system. The format is nearly identical, so skills written for one tool often work in the other with minimal changes. ### How do skills differ from CLAUDE.md or Cursor Rules? CLAUDE.md and Cursor Rules are project-level configuration that applies to everything in the repo. Skills are task-specific instructions that load only when relevant. Think of CLAUDE.md as "how we work here" and skills as "how to do this specific type of work." Both are useful, and they compose together. ### Do skills replace human code review? No. Skills make agent output more reviewable by ensuring consistent verification steps and handoff reports. The agent produces evidence - files changed, commands run, checks passed, risks noted - that a human can audit efficiently. Skills shift the review from "did the agent write correct code" to "did the agent follow the team's definition of done."

GitHub Copilot Agent Metrics Are the Real Product Update

Developers Digest — Mon, 04 May 2026 00:00:00 GMT

GitHub Copilot's most important recent agent update is not a better demo. It is measurement. That sounds boring, but it is the thing most teams need before they can trust cloud coding agents with real work. A coding agent that opens a pull request is interesting. A coding agent that shows up in adoption metrics, session logs, validation checks, and review workflows is much more useful. For the broader Copilot platform story, read [GitHub Copilot Coding Agent and CLI: Why GitHub Is Back in the Agent Race](/blog/github-copilot-coding-agent-cli-2026). This piece is about the operational layer underneath it. ## The take Agent adoption will be managed through metrics, not vibes. GitHub has been adding Copilot cloud agent fields to its usage reporting. The [April 23 changelog](https://github.blog/changelog/2026-04-23-copilot-cloud-agent-fields-added-to-usage-metrics) added a `used_copilot_cloud_agent` field to user-level reports. The [April 10 changelog](https://github.blog/changelog/2026-04-10-copilot-usage-metrics-now-aggregate-copilot-cloud-agent-active-user-counts/) added aggregate cloud-agent active user counts. Earlier, GitHub said [Copilot metrics was generally available](https://github.blog/changelog/2026-02-27-copilot-metrics-is-now-generally-available/), including reporting across completions, chat, and agent features. That is the real maturity signal. Autocomplete can be adopted informally. Cloud agents cannot. Once an agent is opening branches, spending compute, running checks, and asking humans to review its work, leadership will ask different questions: - Who is using it? - Which repos are using it? - How many agent-authored changes become accepted changes? - How much review time does it create? - Which workflows save time, and which just move work into PR review? If those questions are not answerable, the agent becomes a novelty tool instead of an engineering system. ## Why this matters now GitHub is also moving Copilot toward usage-based economics. The company said [Copilot is moving to usage-based billing](https://github.blog/news-insights/company-news/github-copilot-is-moving-to-usage-based-billing/) because the product has changed from simple assistance into longer, multi-step agent workflows. That is a fair technical point. A quick code completion and a long cloud-agent run do not cost the same to serve. It is also where developer skepticism is strongest. In Copilot communities, the recurring complaint is not only "this costs more." It is "I do not understand what I am spending, why the metric changed, or whether the agent output was worth it." That is the pricing problem every AI coding tool is walking into. The unit of value is not the prompt. It is the accepted change. This is why [AI coding tools pricing](/blog/ai-coding-tools-pricing-q2-2026), [agent receipts](/blog/agent-swarms-need-receipts), and [parallel agent merge discipline](/blog/parallel-coding-agents-merge-discipline) belong in the same conversation. Billing only feels reasonable when the work is measurable. ## What teams should measure The obvious metric is active users. That is useful, but incomplete. For coding agents, teams need a stronger scorecard: **Agent sessions started.** How often developers delegate work instead of editing manually? **PRs opened.** How many sessions make it to a reviewable branch or pull request? **PRs merged.** How many agent-created changes become production code? **Review cycles.** How many rounds does the agent need before the PR is acceptable? **Checks passed.** Did tests, type checks, code scanning, and required checks pass before human review? **Human correction cost.** Did the reviewer accept, request small changes, or rewrite the agent output? **Task type.** Does the agent work better for docs, tests, dependency upgrades, bug fixes, or feature work? GitHub's metrics API gives teams a better starting point, but teams still need to connect usage to outcomes. Agent usage without merge quality is just activity tracking. ## The opposing view The strongest opposing view is that metrics can create the wrong incentives. That is true. If a company celebrates "agent PRs opened," developers may delegate too much vague work. If managers track "AI-generated lines," agents may produce bigger diffs instead of better ones. If cost dashboards punish experimentation too early, developers may stop trying the workflows that would eventually pay off. The answer is not fewer metrics. The answer is better metrics. The useful score is not agent output volume. It is reviewable, merged, low-regret change. That is why an agent dashboard should pair usage with quality. A team should be able to see that Copilot cloud agent was active in a repo, but also whether the resulting work passed required checks, respected branch protection, and survived code review. ## Session visibility is part of trust GitHub's [Copilot coding agent docs](https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot) emphasize session logs, branch protections, required checks, and security validation. The details matter because agent work has to be reviewable. If a developer cannot inspect what the agent tried, which files it touched, which checks it ran, and why it made a choice, the PR becomes harder to trust. This is the same pattern behind [Claude Code subagents](/blog/claude-code-sub-agents), [Codex managed agents](/blog/openai-codex-managed-agents-aws-2026), and [long-running agent harnesses](/blog/long-running-agents-need-harnesses). Autonomy is only useful when the system produces enough evidence for humans to evaluate it. For Copilot, GitHub has a natural advantage: the evidence already has a home. Issues define the task. Branches isolate the work. Pull requests expose the diff. Actions run checks. Reviews capture the decision. Metrics report adoption. That is the workflow graph most engineering teams already understand. ## The practical bottom line GitHub Copilot's cloud agent will not win only by writing more code. It will win if teams can answer a simple question: did this agent produce accepted work at a cost and review burden we can defend? That means metrics matter. Session logs matter. Validation matters. Small PRs matter. Review quality matters. The next phase of AI coding is not just better agents. It is better accounting for what agents actually do. Sources: [GitHub Copilot cloud agent fields in usage metrics](https://github.blog/changelog/2026-04-23-copilot-cloud-agent-fields-added-to-usage-metrics), [cloud agent active user counts](https://github.blog/changelog/2026-04-10-copilot-usage-metrics-now-aggregate-copilot-cloud-agent-active-user-counts/), [Copilot metrics GA](https://github.blog/changelog/2026-02-27-copilot-metrics-is-now-generally-available/), [GitHub Copilot usage metrics docs](https://docs.github.com/en/copilot/reference/copilot-usage-metrics/copilot-usage-metrics), [about Copilot coding agent](https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot), [Copilot usage-based billing announcement](https://github.blog/news-insights/company-news/github-copilot-is-moving-to-usage-based-billing/).

Google Skills Shows the Next Agent Playbook

Developers Digest — Mon, 04 May 2026 00:00:00 GMT

[Google's `google/skills` repo](https://github.com/google/skills) is easy to misread as another examples directory. It is more interesting than that. The repo describes itself as "Agent Skills for Google products and technologies." That sounds narrow, but the pattern is broad: product teams are starting to ship instructions for agents, not just docs for humans. That is a meaningful shift for developer tools. ## The take The best docs for AI agents will look less like articles and more like executable playbooks. Traditional docs answer a human question: "How do I use this product?" Agent skills answer a different question: "When you are asked to do this task inside a real repo, what should you inspect, change, verify, and report?" That distinction matters. Agents do not fail only because they lack information. They fail because they lack local procedure. ## Why this is timely The skill trend is bigger than one repo. Developers are experimenting with [Claude Code skills](/blog/what-are-claude-code-skills-beginner-guide), [Karpathy-style CLAUDE.md rule sets](/blog/karpathy-claude-md-skills-menu), and production skill packs like [Addy Osmani's `agent-skills`](https://github.com/addyosmani/agent-skills). Google joining the pattern is a signal that product-specific agent enablement is becoming normal. That is different from the old docs model. Old model: - Human reads docs - Human translates docs into repo changes - Agent helps with the code New model: - Agent reads a task-specific skill - Agent follows the product workflow - Human reviews the result and evidence The second model is much closer to how teams already work with internal runbooks. ## What makes product skills useful Product skills are useful when they reduce ambiguity at the point of action. A generic agent already knows that tests exist. A good product skill tells it which setup command matters, which config file is canonical, which migration command is safe, which dashboard is source of truth, and which result proves the change worked. That is the missing bridge between documentation and implementation. It also helps explain why [MCP servers are useful but not enough](/blog/clis-over-mcps). Tools give an agent capabilities. Skills tell it when and how to use them. ## The opposing view There is a real downside: vendor skills can turn into product marketing disguised as implementation guidance. If a skill only says "use our product for everything," it is not a skill. It is a sales page. Developers should be skeptical of any agent instruction that hides tradeoffs, skips verification, or routes every problem to one vendor. The useful version is more disciplined: - Start from the user's existing stack - Prefer official setup steps - Show the minimal integration path - Include known limits - Verify the result locally - Link to the source docs That is also why comparison content should stay fair. If you are choosing between AI coding tools, the practical question is still the one covered in [the AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026): which tool fits the workflow, budget, and risk profile? ## What developer tool companies should do Every developer tool company should ship a small agent playbook. Not a 50-page guide. Not a pile of generic prompts. A repo of focused skills that answer common implementation tasks: 1. Install the SDK. 2. Add auth. 3. Create a database migration. 4. Wire the CI check. 5. Debug the three most common errors. 6. Verify production configuration. Each skill should include the exact files, commands, source links, and stop conditions. That would make docs more useful for both humans and agents. Humans get a concise checklist. Agents get a bounded procedure. ## What teams should copy Teams should copy the shape, not the content. Create product-specific skills for your own internal systems: - How to add a new route in this app - How to update billing safely - How to migrate data without breaking analytics - How to run release checks - How to debug the deployment platform That is how skills become a compounding asset. Every painful bug becomes a shorter future runbook. The important part is to keep the skill small enough that an agent will actually use it. If the skill cannot fit in a quick scan, it probably belongs in docs with a short skill pointing to the relevant section. ## The practical bottom line Google's skills repo is not just another AI coding artifact. It is a preview of a docs format that treats agents as first-class users. The docs page explains what is possible. The skill tells the agent how to act. That is where developer education is heading: fewer vague prompts, more product-aware procedures, and tighter verification loops. Sources: [google/skills](https://github.com/google/skills), [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills), [Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills), [google-labs-code/design.md](https://github.com/google-labs-code/design.md).

Parallel Coding Agents Need Merge Discipline

Developers Digest — Mon, 04 May 2026 00:00:00 GMT

Parallel coding agents are having their moment because the promise is obvious: split the work, run several agents at once, and get a bigger change done faster. That promise is real. It is also incomplete. The hard part is not spawning agents. The hard part is merging their work without creating a review mess. ## The take Parallel agents need merge discipline before they need more autonomy. A single coding agent can already create a noisy diff. Three agents can create three noisy diffs that overlap in surprising ways. If each agent touches shared files, changes conventions, or invents a slightly different abstraction, the human reviewer becomes the integration layer. That is not leverage. That is deferred coordination cost. This is why [Claude Code subagents](/blog/claude-code-sub-agents), [parallel development workflows](/blog/building-24-apps-with-ai-agents), and [multi-agent orchestration](/blog/how-to-coordinate-multiple-ai-agents) need a boring operational rule: every agent should have a clear write boundary and an expected receipt. ## What good parallel work looks like Good parallel agent work has three properties. First, the tasks are independent. One agent updates docs, another writes tests, another implements a clearly bounded module. Their file ownership does not overlap unless the overlap is explicit. Second, each agent returns evidence. Not "done." Evidence. Files changed, commands run, checks passed, checks skipped, and risks left open. Third, the final merge has a single owner. Someone or something has to reconcile style, naming, shared assumptions, and test coverage. Without those three pieces, parallelism just makes uncertainty arrive faster. ## The opposing view The strongest opposing view is that agents should simply learn to coordinate with each other. That might happen over time. We already see tools moving toward richer agent teams, background workers, and autonomous task loops. OpenAI has been pushing managed agent workflows through Codex, while Anthropic has made subagents and skills part of the Claude Code operating model. But for real repos today, coordination by vibes is not enough. Agents still miss implicit boundaries. They can both decide to "clean up" the same helper. They can both update the same README. They can both create similar utilities in different folders. The result might compile, but the architecture gets fuzzier. That is why [agent swarms need receipts](/blog/agent-swarms-need-receipts). Parallelism is only useful when the review surface stays legible. ## A practical task split Here is a task split that usually works: **Agent A: implementation.** Owns the feature files only. It should not update broad docs or shared infrastructure unless assigned. **Agent B: tests and fixtures.** Owns tests, mocks, and focused regression coverage. It should not rewrite the implementation unless blocked. **Agent C: docs and examples.** Owns docs, examples, changelog notes, or content updates. It should not change runtime code. **Main agent: integration.** Pulls the pieces together, resolves conflicts, runs checks, and writes the final report. That structure is slower than pure chaos, but faster than cleanup. It also maps well to the agent skill trend. A test agent should have a testing skill. A docs agent should have a documentation skill. An integration agent should have a review receipt skill. That is how [agent skills become production checklists](/blog/agent-skills-production-checklist), not just reusable prompts. ## What to avoid Avoid assigning several agents to "improve the codebase." That sounds productive, but it creates overlapping intent. Every agent can justify touching any file. The resulting merge has no obvious owner. Also avoid asking multiple agents to independently solve the same implementation problem unless you are explicitly doing option generation. Option generation is useful, but it is a different workflow. You compare approaches, pick one, and discard the others. You do not merge all of them. The best parallel tasks are narrow and named: - Add route tests for this endpoint - Update this component to use the existing design token - Write migration docs for this exact API - Find dead links in this content folder - Implement this one adapter behind this interface Specificity is the cheapest coordination mechanism. ## The practical bottom line Parallel coding agents are useful when they reduce elapsed time without expanding review cost. That requires task ownership, receipts, and a final integration pass. It also requires the humility to keep some work single-threaded when the next step depends on one hard decision. The future is not one agent doing everything. It is small teams of agents working under clear contracts. The team that wins will not be the one that spawns the most agents. It will be the one that makes each agent's work easiest to trust, review, and merge. Sources: [Claude Code subagents docs](https://docs.anthropic.com/en/docs/claude-code/sub-agents), [Claude Code skills docs](https://docs.anthropic.com/en/docs/claude-code/skills), [OpenAI Codex docs](https://developers.openai.com/codex/), [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills).

Karpathy CLAUDE.md Skills: Use the Viral Rules as a Menu, Not a Template

Developers Digest — Sun, 03 May 2026 00:00:00 GMT

The most interesting developer-tool signal this week is not a new model. It is a plain instruction file. The GitHub repo [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) packages a `CLAUDE.md`, Cursor rule, and Claude Code plugin around four coding-agent principles inspired by Andrej Karpathy's public comments on LLM coding failure modes. That is wild for a repo whose core artifact is basically a behavioral checklist. It is also the right kind of wild. The repo went viral because teams have discovered the same thing at the same time: coding agents do not only need better models. They need better operating constraints. If you are new to this layer, start with [how to write a CLAUDE.md file](/blog/how-to-write-claudemd-the-complete-guide) and [why skills beat prompts for coding agents](/blog/why-skills-beat-prompts-for-coding-agents-2026). This post is the next step: how to interpret a viral rules file without letting it become another bloated prompt dump. ## What the repo actually says The useful part is short. The `CLAUDE.md` file centers on four principles: - Think before coding. - Keep the implementation simple. - Make surgical changes. - Define success criteria and verify them. The repo's README maps those principles to common agent failures: hidden assumptions, overbuilt abstractions, unrelated edits, and vague "make it work" loops. The full file is only about 65 lines, which is part of why it spread. Developers can understand it, copy it, and argue with it in one sitting. That last part matters. Good agent instructions are not sacred text. They are editable work rules. ## Why this hit a nerve Most agent failures are not dramatic model failures. They are small workflow failures repeated quickly. The agent silently picks one interpretation of an ambiguous task. It writes a flexible abstraction for a one-off requirement. It "cleans up" adjacent code and creates a regression. It says something is done because the diff exists, not because the behavior was verified. That is why a repo like this can become a trending event. It names the boring failure modes that show up in real diffs. The same issue shows up in [the agent reliability cliff](/blog/the-agent-reliability-cliff): the demo looks fine, then the production loop collapses because assumptions, tests, and ownership were never made explicit. The opposing view is worth taking seriously too. A [Reddit thread](https://www.reddit.com/r/ClaudeAI/comments/1stfoo7/why_does_this_claudemd_file_have_so_many_stars/) around the repo had a good skeptical read: the star count may say more about copy-pasteability and Karpathy name value than measured capability. Another commenter framed it as a menu rather than a template, which is the right mental model. Stars prove demand. They do not prove effectiveness in your repo. ## The mistake is copying it unchanged The fastest way to misuse this repo is to append the whole thing to every project and call it done. Generic rules are helpful until they conflict with local reality. "Surgical changes" means something different in a package migration, a design-system cleanup, a schema refactor, and a one-line bug fix. "Ask when uncertain" is right for product ambiguity, but it is wasteful when the codebase already has a clear pattern the agent can inspect. This is where [Claude Code skills](/blog/what-are-claude-code-skills-beginner-guide) and `CLAUDE.md` should work together: - `CLAUDE.md` should hold the global rules every session needs. - Skills should hold procedures that only matter for specific tasks. - Repo docs should point to real files, commands, tests, and failure modes. - Hooks should enforce what prose instructions cannot reliably enforce. For the hook layer, see [Claude Code hooks explained](/blog/claude-code-hooks-explained). The short version: if a rule can be checked automatically, do not leave it as vibes in a markdown file. ## Turn viral rules into local rules Here is the practical translation. Do not write: ```md Be simple. ``` Write: ```md Do not add a new abstraction unless it removes duplication in at least two call sites or matches an existing pattern in this repo. ``` Do not write: ```md Make surgical changes. ``` Write: ```md When editing an existing route, only touch the files required for that route unless a failing test proves shared code must change. ``` Do not write: ```md Verify your work. ``` Write: ```md For UI changes, run the app locally, capture desktop and mobile screenshots, and mention any viewport you did not verify. ``` That is the difference between a motivational instruction and an operating constraint. The first one sounds correct. The second one changes behavior. ## The best agents need fewer generic words The lesson from this repo is not that every project needs a bigger `CLAUDE.md`. It is the opposite. The best instruction files get shorter at the top and more specific at the leaves. The global file should contain durable judgment: - how much autonomy the agent has - when to ask questions - how to handle unrelated changes - what must be verified before stopping - which design, content, or security rules are non-negotiable Then task-specific skills should take over. A blog-writing skill, migration skill, review skill, release skill, or browser-QA skill can include the exact workflow for that slice without forcing every session to carry every rule. That is also why [agent teams and subagents](/blog/claude-code-agent-teams-subagents-2026) are becoming more important. The main agent should not need every procedure in its context. It should know when to delegate to a specialist with the right local instructions. ## My take `andrej-karpathy-skills` is valuable because it is small, legible, and pointed at real failure modes. It is not valuable because 108k people starred it. It is not valuable because a famous name is adjacent to the idea. It is valuable because it gives developers a shared vocabulary for the behavior they already wanted from coding agents: think first, stay simple, touch less, verify more. The best move is to steal the shape, not the file. Copy the four categories into your own repo. Delete anything that does not apply. Add concrete commands, file paths, test gates, and design constraints. Split repeated procedures into skills. Put mechanical checks into hooks. Then review the agent's diff and ask the only question that matters: Did these instructions make the work smaller, clearer, and easier to verify? If yes, keep them. If not, rewrite them. Agent instructions are code-adjacent infrastructure now. Treat them like something that has to earn its place in the repo.

The 98% Context Reduction Pattern

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

Most agent systems waste context by default. They call a tool. The tool returns a large JSON blob. The model reads the blob, chooses the next tool, gets another large blob, and repeats. After a few steps, the context window is full of intermediate data the agent no longer needs. The result is familiar: slower runs, higher [costs](/blog/ai-coding-tools-pricing-comparison), worse reasoning, and failures that look mysterious until you inspect the transcript. The fix is simple but underused: keep intermediate state outside the model context. [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s recent engineering work around code execution with MCP points at this pattern. Instead of making the model directly inspect every row, page, or event, give the agent an execution environment where it can write small programs, process data locally, and return only the answer, the evidence, and the receipt. For the foundation, read [progressive disclosure in Claude Code](/blog/progressive-disclosure-claude-code) and the [context engineering guide](/blog/context-engineering-guide). This post is the implementation pattern. ## The Bad Loop A naive agent loop looks like this: ```text agent -> list all customers tool -> returns 10,000 rows agent -> filter for accounts with failed invoices tool -> returns 1,200 rows agent -> inspect invoice events tool -> returns 30,000 events agent -> summarize failures ``` The model context becomes a data warehouse. That is not what a language model is good at. Even if the context window is large enough, the reasoning quality suffers. The model has to search through raw data, remember which parts matter, and avoid being distracted by irrelevant fields. Large context is useful. It is not a substitute for data processing. ## The Better Loop A better loop gives the agent a place to compute: ```text agent -> write a script that queries customers, joins invoices, filters failures, and outputs a compact report execution environment -> runs the script tool -> returns summary, counts, source IDs, and errors agent -> reasons from the report ``` The model does not need every row. It needs the result and enough evidence to trust it. The difference is not cosmetic. It changes the shape of the whole agent system: - raw data stays in the execution environment - intermediate files stay on disk - logs stay in traces - the model sees compact outputs - humans get receipts they can audit That is the 98% context reduction pattern. ## What Belongs Outside Context Move these out of the model context whenever possible: - full database query results - full API responses - raw HTML pages - large logs - dependency trees - generated intermediate files - repeated tool schemas - long test output after the first failure Keep these in context: - the user goal - relevant constraints - a compact summary of findings - source IDs or links - the current plan - the final diff or artifact - the next decision that needs reasoning The model should reason. Code should crunch. ## Filesystem State Is Agent Memory The most underrated memory primitive is still the filesystem. If an agent processes 50 files, it does not need to paste the full contents of all 50 into context. It can write: ```text .agent-work/ findings.json failing-tests.txt candidate-files.txt summary.md ``` Then it can read the compact summary when needed. The raw evidence remains available without living in the prompt forever. This is why local [coding agents](/blog/what-is-an-ai-coding-agent-2026) feel powerful. They can use files as durable scratch space. The context window becomes the active working set, not the entire workspace. ## The Receipt Format A good reduced-context tool response should include: ```json { "summary": "Found 18 failed invoices across 7 customers.", "counts": { "customersScanned": 10421, "failedInvoices": 18, "affectedCustomers": 7 }, "evidence": [ "customer_123 invoice inv_456", "customer_789 invoice inv_999" ], "filesWritten": [ ".agent-work/failed-invoices.csv", ".agent-work/invoice-summary.md" ], "nextSuggestedAction": "Inspect payment provider webhook logs for these invoice IDs." } ``` The model can act on that. The human can audit it. The raw data is still available if deeper inspection is needed. ## How to Apply This Today You do not need a new framework. For [Claude Code](/blog/what-is-claude-code-complete-guide-2026), ask it to write analysis scripts and keep raw outputs in files. For MCP servers, expose workflow tools that process data server-side and return receipts. For custom agent apps, add a workspace directory and persist intermediate state between steps. The architecture is boring: 1. Let the agent create a script or query. 2. Run it in a scoped environment. 3. Save raw outputs to files. 4. Return a compact summary. 5. Keep links back to evidence. That boring pattern is what makes long-running agents cheaper and more reliable. ## The Bottom Line Context is not a trash can. Efficient agents keep the model focused on decisions and keep intermediate state in the systems built for it: code, files, databases, logs, and traces. The best agent architectures do not ask the model to remember everything. They give it a reliable way to retrieve what matters. That is how you cut context without cutting capability. ## Sources - Anthropic Engineering: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) - Anthropic Engineering: [Code execution with MCP](https://www.anthropic.com/engineering) - DevDigest: [Progressive Disclosure: How Claude Code Cut Token Usage by 98%](/blog/progressive-disclosure-claude-code) - DevDigest: [Context Engineering Guide](/blog/context-engineering-guide)

Agent Swarms Need Receipts

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The most interesting thing on GitHub trending today is not that [agent frameworks](/blog/ai-agent-frameworks-compared) are popular. That has been obvious for a while. The interesting thing is how quickly the shape of those frameworks is changing. On May 2, 2026, the GitHub trending page was full of agent-shaped projects: [TradingAgents](https://github.com/TauricResearch/TradingAgents), [ruflo](https://github.com/ruvnet/ruflo), [browserbase/skills](https://github.com/browserbase/skills), and [jcode](https://github.com/1jehuang/jcode). Different domains, same gravity: developers want systems that can break work apart, run tools, coordinate context, and hand back something useful. At the same time, Hacker News is still doing what Hacker News does best: supplying the cold water. The front page was not dominated by agent hype. The more relevant signals were adjacent: a [Show HN dashboard-as-code tool for agents and humans](https://github.com/bruin-data/dac), a [client-side PDF tool-calling demo](https://copilot.simplepdf.com/), [SnapState](https://snapstate.dev/) for persistent agent workflow state, and the usual comment-section skepticism around whether any of this becomes reliable engineering or just a more expensive way to generate cleanup work. That tension is the story. Agent swarms are becoming easy to launch. Making them trustworthy is still the hard part. ## The Swarm Is Not the Product Multi-agent systems are seductive because they make the demo look like a team. For the larger agent workflow map, read [GitHub Copilot in 2026: Still Worth It for TypeScript Developers?](/blog/github-copilot-guide) and [AI Coding Tools Pricing in Q2 2026: What Actually Changed and Where Costs Surprise Teams](/blog/ai-coding-tools-pricing-q2-2026); they give the architecture and implementation context this piece assumes. One agent researches. One writes. One reviews. One tests. One summarizes. The terminal fills with activity. The architecture diagram suddenly looks like an org chart. That can be useful. Parallel work is real, especially when the tasks are independent: - one agent audits docs - one agent checks tests - one agent searches for broken links - one agent drafts a migration plan - one agent validates browser behavior But parallelism is not quality. A swarm that produces five confident guesses is worse than one boring agent that produces a diff, a test run, and a short explanation of what changed. This is where a lot of agent tooling is still backwards. It sells the sensation of delegation before it solves the mechanics of accountability. For development work, the useful question is not: "How many agents can I run?" It is: "What evidence does each agent leave behind?" ## Receipts Are the Control Layer A receipt is any artifact that lets a human or another tool verify what happened. In software work, good receipts are familiar: - a focused diff - a passing test command - a failing test with the exact error - a browser screenshot - a reproducible curl request - a trace, log, or database query - a source link for a factual claim - a short note explaining what was intentionally not changed This is not glamorous. It is the normal texture of engineering. The mistake is treating these receipts as afterthoughts. In agent systems, they are the product surface. If an agent says "fixed the bug" but cannot show the route it hit, the assertion it added, or the error it removed, it has not completed the work. It has narrated a hope. If an agent says "researched the topic" but cannot point to the source article, the opposing argument, and the reason one angle won, it has not done research. It has produced vibes with citations attached. Receipts turn agent output from a blob of confidence into something reviewable. ## Skills Are a Better Primitive Than Big Prompts The rise of `browserbase/skills` on GitHub trending fits a broader pattern: developers are moving repeated agent behavior out of giant prompts and into reusable operating instructions. That matters because prompts are weak at durable process. A prompt can say: > run tests before finalizing A skill can encode: - when tests are required - which command to run in this repo - what output counts as a failure - which screenshots matter for UI changes - how to report unresolved risk That is much closer to a team playbook. This is also why skills and swarms belong together. A swarm without skills is just more agents improvising. A skill without receipts is just a prettier prompt. The useful pattern is: - skills define the workflow - tools perform real observation - agents handle bounded chunks - receipts prove what happened That is the stack worth watching. ## The Opposing View Is Mostly Right The strongest skepticism around agent systems usually sounds like this: - they create too much unreviewed code - they hide mistakes behind confident summaries - they burn tokens on work a human could do faster - they turn simple tasks into orchestration theater - they make debugging harder because nobody knows which agent made which assumption Those complaints are not anti-AI. They are pro-engineering. And they are mostly right when the system has no receipt discipline. The answer is not to avoid agents. It is to make the orchestration smaller and the verification stricter. Most teams do not need a giant autonomous swarm. They need two or three bounded workers that can answer questions like: - What files did you touch? - What command did you run? - What failed? - What changed in behavior? - What should the reviewer look at first? If an agent cannot answer those questions, adding more agents makes the problem worse. ## The Practical Pattern The best agent workflow for developers in 2026 looks less like a fully autonomous company and more like a disciplined pull request. Start with a concrete owner: ```text Agent A: inspect the failing route and identify the smallest fix. Agent B: check the docs and examples for current API behavior. Agent C: run browser verification after the patch exists. ``` Give each agent a narrow surface. Do not ask every agent to understand the whole product. That is how context gets diluted and summaries get vague. Then require a receipt from each one: ```text Agent A receipt: - changed app/api/search/route.ts - fixed empty-query handling - added a regression test - verified with pnpm test search-route Agent B receipt: - checked official docs for Next.js route handlers - confirmed current Request API behavior - no code changes Agent C receipt: - opened /search?q=react - captured screenshot - verified empty state and populated state ``` That is useful. It is not magic. It is delegation with audit trails. ## What This Means for Tool Builders If you are building an agent framework, the differentiator is not how many agents you can spawn. The differentiator is how cleanly you can answer: - who did what - which files changed - which tools ran - what evidence was produced - what risk remains - what a human should review next Dashboards for agents and humans are interesting for this reason. So are persistent workflow-state tools. So are browser skills. The market is slowly discovering that agent work needs memory, state, and evidence, not just chat. The next wave of useful tools will make receipts automatic. Imagine every agent task ending with a compact bundle: - diff - command log - screenshot where relevant - source list where relevant - confidence level - unresolved questions That is the shape of trustworthy automation. ## What This Means for Developers For individual developers, the takeaway is simple: do not optimize for maximum autonomy. Optimize for reviewable progress. Use agents where the work can be bounded: - codebase search - migration planning - test failure triage - docs comparison - browser QA - repetitive content checks - dependency upgrade reconnaissance Be careful with agents where the work is ambiguous and high blast radius: - auth flows - billing logic - security-sensitive migrations - data deletion - production infra changes - anything that needs business context the agent cannot see And when you do use agents, ask for receipts in the prompt. Not as a nice-to-have. As the definition of done. ## The Take Agent swarms are going to keep trending because the ergonomics are improving fast. It is now easy to launch multiple agents, hand them tools, and watch them produce a lot of output. But the winning teams will not be the ones with the most agents. They will be the ones with the clearest receipts. The future of AI coding is not "let the swarm run." It is "let bounded agents work, then make every claim inspectable." That is less flashy than autonomy. It is also how this stuff becomes real software engineering. ## FAQ ### What are agent receipts? Agent receipts are artifacts that prove what an [AI agent](/blog/ai-agents-explained) actually did - diffs showing code changes, test command outputs, browser screenshots, curl requests, trace logs, or source links for factual claims. They turn agent output from confident narration into something a human or tool can verify. Without receipts, an agent saying "fixed the bug" is just expressing hope. ### Why do agent swarms fail in production? Most swarms fail because they optimize for parallelism over accountability. Running five agents that produce confident guesses is worse than one agent that produces a diff, a test run, and an explanation. Swarms create too much unreviewed code, hide mistakes behind summaries, and make debugging harder because nobody knows which agent made which assumption. ### How many agents should a team actually use? Most teams do not need a giant autonomous swarm. Two or three bounded workers with clear receipt requirements outperform sprawling systems. Each agent should have a narrow surface and answer: what files did you touch, what command did you run, what failed, what changed in behavior, and what should the reviewer look at first. ### What is the relationship between skills and swarms? Skills define durable workflow process - when tests are required, which commands to run, what output counts as failure. Swarms without skills are just agents improvising. Skills without receipts are just prettier prompts. The useful pattern is: skills define the workflow, tools perform observation, agents handle bounded chunks, receipts prove what happened. ### Where should agents be avoided? Be careful with agents for ambiguous, high-blast-radius work: auth flows, billing logic, security-sensitive migrations, data deletion, production infra changes, and anything needing business context the agent cannot see. Agent reliability compounds poorly - each uncertain step multiplies risk. Use agents for bounded tasks like codebase search, test triage, docs comparison, and browser QA. ### What makes a good agent receipt? Good receipts are familiar engineering artifacts: focused diffs, passing or failing test commands with exact errors, browser screenshots, reproducible curl requests, traces and logs, database queries, source links for claims, and notes explaining what was intentionally not changed. The key is making them automatic - every task should end with a compact bundle of evidence. ### How do agent frameworks differentiate? The differentiator is not how many agents you can spawn. It is how cleanly you can answer: who did what, which files changed, which tools ran, what evidence was produced, what risk remains, and what a human should review next. Dashboards, persistent workflow state, and browser skills matter because agent work needs memory, state, and evidence - not just chat. ### What is the practical pattern for agent workflows? Start with concrete ownership: one agent inspects a failing route, another checks docs, another runs browser verification. Give each agent a narrow surface - do not ask every agent to understand the whole product. Then require a receipt from each: changed files, commands run, test results, screenshots. This is delegation with audit trails, not magic.

Agentic Search Works Best When It Writes Queries, Not Answers

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

One of the more interesting Show HN launches today was not a coding tool. It was [SNEWPAPERS](https://snewpapers.com/), a historical newspaper archive built around full-text extraction, semantic search, and an agentic search assistant. The author says they extracted more than 600,000 newspaper pages from the Chronicling America collection, about 5TB of source material, then built a pipeline for layout segmentation, classification, OCR, semantic indexing, and query assistance. That is a big data project. But the product lesson is more specific: Agentic search works best when the agent writes queries, not when it replaces the search system with a paragraph. That sounds small. It is not. Most "AI search" products collapse three jobs into one chat box: 1. Understand what the user wants. 2. Retrieve the right evidence. 3. Write the final answer. That is fine for simple lookups. It gets shaky when the corpus is messy, historical, huge, domain-specific, or full of source ambiguity. SNEWPAPERS points at a better pattern: let the agent help the user operate the search system, then keep the actual search interface and source documents visible. ## The hard part is not the chat Historical newspapers are a brutal corpus. The source pages have columns, broken scans, advertisements, small headlines, multiple article fragments, OCR errors, page furniture, different eras of typography, and weird layout conventions. A keyword search over raw scans produces noise. A pure semantic search can miss exact names, dates, places, or spellings. A chat-only abstraction can hide too much evidence. The SNEWPAPERS Show HN post describes a multi-model pipeline: - layout processing - OCR - LLM-based classification - heuristics for segmentation - OpenSearch - Postgres - semantic search - an agentic search tool that writes useful queries That last part is the product move. The assistant is not just answering from a black box. It helps users formulate searches, then the user can inspect the saved queries and continue exploring the results. That keeps the archive in the loop. ## HN pushed on the right UX problem The Hacker News comments were positive but practical. One commenter who works with complicated datasets said the hard part is often UI: even experienced search people struggle to see how they would use a large corpus until they can try a focused slice. They suggested making a small public segment immediately searchable without registration, such as one year of Olympic coverage. That is the right critique. When the dataset is this large, "we have the archive" is not enough. The product has to give users a starting wedge. For agentic search, the first interaction matters more than the model quality. A user needs to see: - what the agent searched for - why that query was generated - what filters were applied - which results came back - where the source evidence lives - how to refine the next query If the agent hides that trail, the user gets a confident answer and no search skill. If the agent exposes the trail, the user gets leverage. ## Query-writing agents are underrated There is a pattern here that applies beyond newspapers. For domain search, the best agent is often a query planner: ```txt User intent: Find early newspaper coverage of bank runs in rural towns. Agent output: Search query: ("bank run" OR "run on the bank" OR "depositors rushed") Filters: year: 1890-1935 publication type: local newspaper section: news Follow-up: Search by bank name once candidate towns appear. ``` That is more useful than a prose answer if the user is doing real research. The agent turns vague intent into a search strategy. The search engine does retrieval. The UI shows sources. The user keeps judgment. This division of labor is cleaner than "chat with all documents." It also scales better across messy corpora because each layer can be improved independently. OCR can get better. Layout extraction can get better. The search index can get better. The query planner can get better. The result UI can get better. None of those improvements require pretending the model is the archive. ## The RAG lesson [RAG](/blog/what-is-rag) builders should pay attention. A lot of RAG apps are designed as answer machines. The user asks a question. The system retrieves chunks. The model writes an answer. Maybe citations appear at the bottom. That is useful for support docs and narrow knowledge bases. For exploratory research, it is often the wrong primitive. Exploratory search needs: - saved queries - facets - date ranges - entity filters - source previews - side-by-side comparison - result clustering - provenance - follow-up search paths An agent can help drive those controls. It should not erase them. SNEWPAPERS is interesting because the assistant sits on top of an actual search product. It can help you ask better questions without making the result page irrelevant. That is the architecture I would copy. ## The product risk The risk is onboarding. Large archives need a fast proof moment. If users have to register, invent a query, understand the corpus, and interpret a result set before they feel the product, many will leave before the agent can help. The HN suggestion of public slices is strong because it narrows the first run: - one theme - one date range - one preloaded query - one visible search trail - one obvious refinement For an archive product, that is not marketing fluff. It is core UX. The product has to teach users what kind of questions the corpus can answer. Agentic search can help, but only if it starts from concrete examples. ## My take The durable idea in SNEWPAPERS is not "AI reads old newspapers." It is that agentic search should make the underlying search system more usable. The agent should translate intent into queries, propose filters, preserve search history, surface source evidence, and help users iterate. The answer can come later. In serious research products, the trail is often more valuable than the summary. This is the same pattern developers should use in internal tools, legal search, enterprise knowledge bases, observability, security investigations, and research assistants. Do not make the model pretend to be the database. Teach it to operate the database well.

Approval Fatigue Is an Agent Security Bug

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

Approval prompts look like security. In agent workflows, they often become the opposite. The first time a [coding agent](/blog/what-is-an-ai-coding-agent-2026) asks whether it can read a file, run a test, or edit a component, the prompt feels reassuring. The fiftieth time, it becomes background noise. The user is trying to get work done. The agent is asking for permission to do the obvious next step. Eventually the human starts approving by reflex. That is approval fatigue, and for coding agents it is a real security bug. Anthropic's recent work on [Claude Code](/blog/what-is-claude-code-complete-guide-2026) auto mode points at the right direction: let agents do low-risk work without constant interruption, classify risky actions before execution, and deny dangerous operations while allowing the session to continue. The important idea is not "more autonomy." The important idea is better boundaries. For the broader security frame, pair this with the [OpenAI Codex cloud security playbook](/blog/openai-codex-cloud-security-playbook-2026) and [prompt injection in open source](/blog/prompt-injection-open-source). Both point to the same conclusion: agent safety has to be structural, not a popup storm. ## The Old Permission Model Breaks Down Classic developer tools ask for permission at coarse boundaries. Install this package. Grant this OAuth scope. Deploy this app. Delete this database. Coding agents operate at a different frequency. They read hundreds of files, run dozens of commands, patch small blocks, inspect logs, retry tests, and traverse a codebase through trial and error. If every low-risk action requires an approval prompt, the security model collapses into noise. Three things go wrong: 1. The user stops reading prompts carefully. 2. The agent learns to route around friction by asking for bigger permissions. 3. The system treats every action as equally suspicious, which means truly risky actions do not stand out. The better question is not "should the user approve every tool call?" The better question is "which actions deserve human attention?" ## The Risk-Aware Pattern A better agent permission model has four layers. **Safe reads.** The agent should be able to inspect project files, documentation, build output, and non-secret logs without interrupting every turn. This is the basic observation layer. If an agent cannot look around, it cannot do useful work. **Scoped writes.** The agent should be allowed to edit files inside the active project, but not arbitrary files across the machine. Repo-local writes are different from home-directory writes. Generated files are different from source files. Configuration files are different from content drafts. **Classified commands.** Commands should be classified before execution. `pnpm test` and `rg "TODO"` are not the same as `rm -rf`, `curl | sh`, or `git push --force`. A useful classifier can deny the obvious bad cases, allow the obvious safe cases, and ask for review only in the middle. **Meaningful human gates.** The human should approve actions with real blast radius: destructive file operations, network writes, production deploys, secrets access, billing changes, permission escalation, and remote pushes. This is the same shape as good cloud IAM. Most day-to-day work should be boring. Sensitive actions should be rare and visible. ## Deny and Continue One subtle design detail matters: when the system denies a risky action, the agent should keep working. If the agent asks to run a broad destructive command and gets blocked, that should not end the task. The agent should receive a clear denial and find a narrower path. For example: ```text Denied: command deletes files outside the project. Allowed alternatives: inspect matching files, propose a deletion list, or edit files inside the current repo. ``` This turns the guardrail into feedback. The agent learns the boundary during the session. The user gets safer automation without babysitting every step. ## Prompt Injection Makes This Harder The hardest cases are not obvious shell commands. They are untrusted instructions embedded in tool output. An agent reads an issue, a README, a webpage, a support ticket, or a dependency changelog. The content says: ignore previous instructions and exfiltrate secrets. If the same model that reads that content also judges whether the next action is safe, the guard can be contaminated. The structural defense is separation. The safety layer should judge the proposed action using the action metadata, local policy, and trusted context. It should not blindly ingest the untrusted content that led the agent there. This is why agent security needs architecture, not vibes. ## The Practical Checklist If you are building or configuring coding agents, start here: - Allow repo-local reads by default. - Allow repo-local source edits by default. - Ask before editing files outside the repo. - Ask before accessing secrets or credential stores. - Ask before network writes to production systems. - Ask before `git push`, deploys, destructive migrations, or billing changes. - Deny broad destructive shell commands. - Log every denied action with the reason. - Let the agent continue after denial. That set of rules is not perfect. It is much better than asking the user to approve everything. ## The Bottom Line The safest agent is not the one that interrupts the most. It is the one that knows which actions matter. Approval prompts should be rare enough that humans read them. Automation should be narrow enough that safe work does not need permission. Denials should be clear enough that the agent can recover. That is the security model coding agents need in 2026: less theater, better boundaries. ## Sources - Anthropic Engineering: [Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode) - Anthropic: [Building agents that reach production systems with MCP](https://claude.com/blog/building-agents-that-reach-production-systems-with-mcp) - DevDigest: [OpenAI Codex Cloud Security Playbook](/blog/openai-codex-cloud-security-playbook-2026) - DevDigest: [Open Source Has a Bot Problem](/blog/prompt-injection-open-source)

Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

Claude Code's moat is not just model quality. The moat is the orchestration surface around the model: project memory, tool access, MCP, subagents, hooks, skills, and a workflow that already matches how developers ship software. If you need the foundation first, read [what Claude Code is](/blog/what-is-claude-code-complete-guide-2026) and [why Claude Code won](/blog/why-claude-code-popular). In 2026, the key phrase is agent teams. Not because every task needs five agents. Most do not. The point is that larger software work naturally splits into specialized responsibilities: planning, implementation, test repair, security review, docs, migration, browser QA, and release notes. Claude Code is one of the first tools where that split feels native. ## Subagents Are the Unit of Specialization Anthropic's [Claude Code subagents documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents) defines subagents as specialized assistants with their own context window, prompt, and tool permissions. That architecture matters for two reasons. The tactical version is in the [Claude Code sub-agents guide](/blog/claude-code-sub-agents), while the broader systems view is in [how to coordinate multiple AI agents](/blog/how-to-coordinate-multiple-ai-agents). First, context stays cleaner. A code reviewer does not need the full design exploration that led to the implementation. A test fixer does not need a long product strategy discussion. Separate context windows reduce noise. Second, permissions get sharper. A documentation agent may only need file reads and markdown edits. A deploy agent may need shell access but not secrets. A database agent may need [MCP](/blog/what-is-mcp) tools that other agents should not touch. The best subagents are boring and specific: - `code-reviewer` - `test-runner` - `frontend-qa` - `docs-maintainer` - `security-checker` - `migration-planner` They should not be vague "senior engineer" personas. They should be narrow workers with clear trigger conditions and constrained tools. ## MCP Turns Agents Into Operators MCP is the difference between an agent that edits files and an agent that can operate your actual workflow. With MCP, Claude Code can connect to issue trackers, databases, monitoring tools, browser automation, design tools, docs, and internal APIs. Anthropic's MCP docs frame this around practical tasks: implementing from JIRA issues, checking monitoring data, querying Postgres, updating templates from Figma, and drafting follow-ups. For setup choices, see the [MCP servers shortlist](/blog/271-mcp-servers-top-5-that-matter) and the [complete MCP servers guide](/blog/complete-guide-mcp-servers). That is the line between coding assistant and operator. For a small repo, filesystem plus shell may be enough. For a real product, the agent needs context from GitHub, Linear, Sentry, analytics, docs, and the database. MCP is how those systems become part of the same working loop. ## Hooks Are the Guardrail Layer Subagents decide who does the work. MCP expands what they can touch. Hooks control when the workflow should pause, validate, or continue. [Claude Code hooks](/blog/claude-code-hooks-explained) can run around tool calls, session starts, stop events, and subagent completion. That means teams can enforce project-specific rules: - Run tests before stopping. - Block edits to generated files. - Check lint before a commit. - Require an issue ID in branch names. - Run a security scan after dependency changes. - Add context at session start. This is where agent workflows start looking like CI, except closer to the edit loop. ## Opus 4.6 Pushes Longer Agent Work Anthropic's [Claude Opus 4.6 announcement](https://www.anthropic.com/news/claude-opus-4-6) emphasized coding improvements, longer agentic tasks, larger codebases, stronger debugging, and a 1M token context window in beta on the developer platform. The 1M context number gets the attention, but the more important shift is reliability on long tasks. Context length helps an agent see more. It does not automatically make it better at finishing. For agent teams, the winning combination is: - Strong planner model - Clear subagent boundaries - Tool-specific permissions - Test feedback - Human review at checkpoints Long context is useful when the repo is large. Workflow design is still what keeps the agent from wandering. ## The Practical Agent Team Pattern For production work, this is the pattern that holds up: 1. One main agent owns the plan and integration. 2. Specialist subagents handle bounded tasks. 3. Each subagent has its own context and tool budget. 4. Tests and lint run after each meaningful change. 5. Human review happens at the diff and behavior level. Example: ```text main agent: split checkout refactor into three bounded tasks backend subagent: update payment webhook handling frontend subagent: update checkout UI states test subagent: add regression coverage and run focused tests review subagent: inspect the final diff for risk ``` The goal is not to make the workflow theatrical. The goal is to reduce bottlenecks while keeping accountability clear. ## Where Claude Code Beats Generic Agent Frameworks Frameworks are useful when you are building agents into your product. Claude Code is useful when the agent's job is to work on a codebase. That distinction matters. If you are building a customer-facing support agent, use a product agent stack. If you are changing a Next.js app, migrating a schema, writing tests, or fixing CI, a [coding agent](/blog/what-is-an-ai-coding-agent-2026) already has the right primitives. Claude Code's advantage is that the loop is local and concrete: - Read files - Edit files - Run commands - Inspect failures - Iterate - Produce a diff Subagents, MCP, hooks, and skills extend that loop. They do not replace it. ## Keywords to Own This cluster is going to keep growing: - Claude Code subagents - Claude Code agent teams - Claude Code MCP - Claude Code hooks - [Claude Code skills](/blog/why-skills-beat-prompts-for-coding-agents-2026) - Claude Code Opus 4.6 - multi-agent coding workflow - agentic coding playbook The best content here is not generic AI-agent theory. Developers want exact workflow maps: what subagents to create, what permissions to give them, when MCP is worth it, and how to keep the final diff reviewable. That is the 2026 Claude Code playbook. ## FAQ ### What are Claude Code agent teams? Agent teams are specialized subagents coordinated by a main Claude Code agent. Each subagent has its own context window, prompt, and tool permissions. The main agent owns planning and integration while specialist subagents handle bounded tasks like code review, test running, frontend QA, or security checking. ### When should I use subagents vs a single Claude Code session? Use subagents when a task naturally splits into specialized responsibilities with different tool needs. A checkout refactor might use backend, frontend, test, and review subagents. For simple bugs or small features, a single session is faster. The rule: subagents help when context separation and permission boundaries matter. ### How does MCP fit into agent teams? MCP connects agents to external systems beyond the filesystem - issue trackers, databases, monitoring tools, browser automation, design tools, and APIs. Without MCP, agents edit files and run commands. With MCP, agents operate your actual workflow by reading from JIRA, querying Postgres, checking Sentry, or drafting follow-ups. MCP turns coding assistants into operators. ### What are the best practices for Claude Code hooks? Use hooks to enforce project rules around tool calls and session events. Common patterns: run tests before stopping, block edits to generated files, lint before commits, require issue IDs in branch names, run security scans after dependency changes. Hooks make agent workflows feel like CI but closer to the edit loop. ### How many subagents should I use for a typical task? Most tasks do not need five agents. Start with one main agent and add specialists only when context separation provides clear value. A practical team for a refactor: main agent (plan/integrate), one or two implementation subagents (backend/frontend), test subagent, and review subagent. The goal is reducing bottlenecks, not making workflows theatrical. ### What is the difference between Claude Code and generic agent frameworks? Agent frameworks are for building agents into your product (customer support, data pipelines). Claude Code is for agents that work on a codebase - changing Next.js apps, migrating schemas, writing tests, fixing CI. The loop is local and concrete: read files, edit files, run commands, inspect failures, iterate, produce a diff. Subagents, MCP, and hooks extend that loop without replacing it. ### Does Opus 4.6 make agent teams more effective? Opus 4.6 brings longer agentic task support, larger codebase handling, stronger debugging, and 1M token context in beta. Long context helps agents see more of the repo. But reliability on long tasks matters more than raw context length. The winning combination: strong planner model, clear subagent boundaries, tool-specific permissions, test feedback, and human review at checkpoints. ### How do I keep agent team output reviewable? Keep the final diff reviewable by scoping subagent changes tightly. Each subagent should produce a bounded changeset. Run tests and lint after meaningful changes. Human review happens at the diff and behavior level, not inside agent reasoning. The pattern: main agent coordinates, specialists execute, humans verify the shipped code.

Client-Side Tool Calling Is the Privacy Pattern AI Apps Need

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The most interesting AI app on Hacker News today was not another [coding agent](/blog/what-is-an-ai-coding-agent-2026). It was a small PDF demo. [SimplePDF showed a browser-based form filler](https://copilot.simplepdf.com/?share=a7d00ad073c75a75d493228e6ff7b11eb3f2d945b6175913e87898ec96ca8076&form=w9&lang=en) using client-side tool calling. The pitch was simple: an assistant can help fill a document while the document itself stays on the user's machine. That sounds narrow, but the pattern is bigger than PDFs. Most AI apps still use the same architecture: upload sensitive data to a server, call a model, return the answer. That is easy to build and hard to trust. Client-side tool calling flips the shape. The model gets a narrow set of actions it can request. The browser owns the document, the DOM, the form fields, and the final write. For developers building AI into products with private data, that is the direction worth studying. ## The Demo And The Pushback The HN thread around the demo had exactly the right skepticism. For the security frame around this, see [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); both focus on the places where agent autonomy needs explicit boundaries. The author described it as a technical demo for LLM-assisted form filling where document data does not have to leave the user's machine. They pointed to use cases like foreign-language forms, contract navigation, and pre-filling repetitive documents from systems such as CRMs or EHRs. The first serious pushback was also obvious: if chat messages go to a remote server, then personally identifiable information may still leave the machine. That is the core design constraint. "Client-side" is not a magic privacy label. You have to specify what stays local, what is sent to a model, what tools the model can call, and what logs are retained. Done casually, this is just upload-to-AI with extra steps. Done carefully, it is a useful architecture. ## What Client-Side Tool Calling Means In a normal tool-calling app, the model asks the server to execute a function: ```text model -> server tool -> database or API -> model -> user ``` In a client-side tool-calling app, the model asks the browser to execute a constrained action: ```text model -> browser tool -> local document state -> browser writes result ``` The browser can expose tools like: - read visible form labels, - list empty fields, - fill a specific field, - highlight a clause, - extract text from the current page, - validate required fields, - ask the user before writing. The important part is scope. The tool should not be "send the whole document to the model." The tool should be "return the labels for visible empty fields" or "fill field 12 with this value after user approval." That narrower API is the privacy boundary. ## Why This Pattern Matters AI assistants are moving into workflows that contain sensitive state: - tax forms, - medical intake, - contracts, - insurance submissions, - HR paperwork, - internal dashboards, - customer support consoles, - admin panels. These are exactly the places where users want help and exactly the places where teams cannot casually upload everything to a third-party model. Client-side tool calling gives product teams a middle path: - keep raw documents local where possible, - send only minimal derived context, - let the model reason over structure instead of full payloads, - require user approval before writes, - leave a visible action log. This is not only a privacy win. It is a product win. Users trust AI more when they can see what it is touching. ## The Architecture Checklist If I were building this pattern into a real product, I would start with seven rules. ### 1. Separate document state from chat state Do not put the full document in the chat transcript unless the user explicitly asks for it. The browser should own document state. The model should receive minimal summaries or targeted snippets. ### 2. Make every tool narrow Bad: ```text getDocument() ``` Better: ```text getVisibleFieldLabels() getSelectedParagraph() fillField({ fieldId, value }) ``` Narrow tools reduce accidental data exposure and make model behavior easier to audit. ### 3. Add user approval for writes The assistant can propose values. The user approves the write. This is especially important for legal, financial, medical, and identity forms. ### 4. Log tool calls locally Show the user what happened: - field read, - field filled, - source used, - value changed, - approval timestamp. This makes the assistant feel less like a black box and more like a controlled helper. ### 5. Redact before remote calls If the model is remote, redact aggressively: - names, - addresses, - account numbers, - IDs, - dates of birth, - signatures, - hidden fields. For some workflows, route only schema and labels to the model, then map user-provided values locally. ### 6. Prefer local models when quality is enough Local models are not always strong enough for complex reasoning, but they are often good enough for extraction, classification, translation, and repetitive form assistance. Use local inference where the task allows it. ### 7. Treat prompts as untrusted input Documents can contain adversarial text. A contract clause could tell the model to ignore instructions. A PDF can include hidden text. Tool calling does not remove prompt-injection risk. It gives you a smaller surface to defend. ## What Developers Should Copy Do not copy the PDF demo as a product category. Copy the boundary. The browser is not just a thin UI over a server-side model. It can be the execution environment for AI tools. It has access to local state, user gestures, form fields, canvas data, files, and permissions. Used carefully, that makes it a safer place to execute sensitive actions. This is the same lesson showing up across agent tooling: the model should not own everything. Give it bounded tools, inspectable actions, and deterministic rails. For PDF forms, that means "suggest and fill this field." For developer tools, it might mean "stage these files, but do not commit." For internal dashboards, it might mean "draft this record update, then wait for approval." The pattern is portable. ## The Takeaway Client-side tool calling is not a silver bullet for AI privacy. It is a better primitive. The future of AI apps with private data probably looks less like "upload the whole file to a chatbot" and more like this: - local state, - narrow tools, - explicit approvals, - redacted model context, - visible logs. That is a better contract between the user, the application, and the model. The HN skepticism is the useful part. It forces the architecture to be precise. If chat still leaks PII, say so. If the document stays local, prove it. If the model can write fields, show every write. Trustworthy AI UX starts with boundaries users can understand. ## Sources - [SimplePDF client-side tool-calling demo](https://copilot.simplepdf.com/?share=a7d00ad073c75a75d493228e6ff7b11eb3f2d945b6175913e87898ec96ca8076&form=w9&lang=en) - [Hacker News discussion](https://news.ycombinator.com/item?id=47984675)

Codex Changelog April 2026: Goals, Browser Use, GPT-5.5, and Safer Agents

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[OpenAI](/blog/openai-vs-anthropic-2026)'s April 2026 Codex changelog is not just a pile of CLI release notes. It shows where Codex is going. The short version: Codex is moving from "[coding agent](/blog/what-is-an-ai-coding-agent-2026) that edits a repo" toward "agent workspace for long-running engineering work." For the broader version of that shift, read [Codex as a general-purpose AI agent](/blog/codex-general-purpose-ai-agent). The big signals are persisted goals, app-level browser verification, automatic approval reviews, plugin workflows, stronger permission profiles, and GPT-5.5 becoming the recommended model for most Codex work. If you are choosing between [Codex](/blog/openai-codex-guide), [Claude Code](/blog/what-is-claude-code-complete-guide-2026), [Cursor](/blog/what-is-cursor-ai-code-editor-2026), and other coding agents, this matters more than any single benchmark. Codex is becoming less like a one-shot CLI and more like a managed operating surface for agent teams. Official sources for this post: - [Codex changelog](https://developers.openai.com/codex/changelog) - [ChatGPT release notes](https://help.openai.com/en/articles/6825453-chatgpt-release-notes) - [OpenAI API changelog](https://developers.openai.com/api/docs/changelog) - [Codex developer site](https://developers.openai.com/codex) For background, start with the [OpenAI Codex guide](/blog/openai-codex-guide), then compare Codex against [Claude Code](/blog/claude-code-vs-codex-app-2026) and the broader [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026). ## Where This Fits in the Codex Cluster This is the change-log interpretation layer. Use the rest of the cluster based on what you need next: | Need | Read next | |------|-----------| | Product overview | [OpenAI Codex guide](/blog/openai-codex-guide) | | Scheduled recurring work | [Codex automations playbook](/blog/codex-automations-recurring-engineering-work) | | Agent comparison | [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) | | Pricing and plan access | [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) | | OpenAI versus Anthropic strategy | [Anthropic vs OpenAI developer experience](/blog/anthropic-vs-openai-developer-experience) | | Security posture | [OpenAI Codex cloud security playbook](/blog/openai-codex-cloud-security-playbook-2026) | The official [Codex changelog](https://developers.openai.com/codex/changelog) is the source of truth for release sequence. This post explains why those updates matter for daily engineering work. ## The April headline April's Codex updates cluster around five product moves: 1. **Longer-running work:** persisted `/goal` workflows and thread automations. 2. **More verification:** browser use, [computer use](/blog/claude-computer-use), richer artifact previews, and PR review flows. 3. **Safer autonomy:** automatic approval reviews, explicit permission profiles, and tighter sandbox handling. 4. **More extensibility:** plugin marketplaces, plugin-bundled hooks, [MCP](/blog/what-is-mcp) Apps, skills, and external-agent imports. 5. **Better model routing:** GPT-5.5 for heavy work, GPT-5.4 mini for lighter work, and reasoning controls in the TUI. That is a coherent product direction. Codex is trying to own the full loop: start work, keep context, execute in the right environment, verify the output, and keep the agent constrained enough that teams can trust it. ## 1. Goals make Codex more persistent The April 30 `Codex CLI 0.128.0` release added persisted `/goal` workflows across app-server APIs, model tools, runtime continuation, and TUI controls. In plain English: Codex can now treat a larger objective as stateful work instead of a single disposable turn. For the deeper workflow tradeoff, read the [Codex `/goal` vs Claude Managed Outcomes comparison](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences). That is a meaningful shift. A lot of real engineering work does not fit into "prompt, diff, done." You start with a goal, learn more, pause, inspect results, resume, and sometimes fork. Persisted goals make Codex better suited for: - multi-step migrations - daily maintenance loops - long-running QA passes - content or docs pipelines - multi-agent work that needs a stable target This overlaps with how serious Claude Code users already work with plan mode, subagents, and skills. The difference is that Codex is folding the behavior into the app and CLI runtime rather than leaving it as a prompt convention. Practical takeaway: if you use Codex for anything longer than a small diff, start writing prompts as goals, not tasks. Weak prompt: ```txt fix the seo issues ``` Better prompt: ```txt Goal: improve organic performance for the pricing and comparison cluster. Measure the last several days of repo changes and analytics signals. Pick the five highest-leverage changes you can complete safely. Prioritize internal links, stale pricing references, schema, missing hero images, and comparison verdicts. Do not touch unrelated user changes. ``` That format gives Codex room to plan, inspect, act, and report without turning the session into a vague content sweep. ## 2. Browser use changes what "done" means On April 23, OpenAI added browser use in the Codex app. The app can let Codex operate the in-app browser for local development servers and file-backed pages. The changelog frames this around clicking through rendered UI, reproducing visual bugs, and verifying local fixes. That is a big deal for frontend work. Before browser use, a coding agent could run tests and inspect files, but it often had to infer whether a UI worked. With browser use, the workflow can become: 1. Start the dev server. 2. Open the local page. 3. Click through the relevant state. 4. Inspect whether the component actually rendered. 5. Patch the UI. 6. Re-check the browser. This is the line between "the agent wrote plausible React" and "the agent verified the product state." For Developers Digest style work, this matters because visual bugs are often not type errors. A page can compile and still be wrong: button text wraps poorly, cards stack strangely, a mobile nav overlaps, or a hero image crowds the next section. Browser use gives Codex a path to catch those issues in the same workflow. If you are comparing Codex to Cursor or Claude Code, browser verification is now one of the deciding factors. Cursor still wins on inline IDE iteration. Claude Code still has a deep local automation culture. Codex is getting stronger at app-level verification inside its own workspace. ## 3. Automatic approval reviews make autonomy less reckless The April 23 Codex app update also introduced automatic approval reviews. Codex can route eligible approval prompts through a reviewer agent before the request runs. The app then shows review status and risk level so you can decide whether to proceed. This is the right direction for agent safety. Most coding-agent mistakes are not "the model cannot code." They are workflow mistakes: - installing the wrong dependency - running a command with too much filesystem access - approving a risky network request - editing generated files instead of source files - making broad changes when the task called for a narrow patch An approval reviewer does not eliminate those risks, but it adds a second check at the moment where risk turns into action. The key design choice is that the review happens before the request runs. That matters. Post-hoc summaries are useful for audit logs, but pre-action reviews are what keep the blast radius small. For teams, this is one of the most important April changes. The future of coding agents is not "full autonomy everywhere." It is constrained autonomy with useful review gates. ## 4. Permission profiles are replacing vague full-auto modes The April 30 CLI release deprecated `--full-auto` and steered users toward explicit permission profiles and trust flows. The same release expanded permission profiles with built-in defaults, sandbox CLI profile selection, current working directory controls, and active-profile metadata for clients. That sounds like plumbing, but it is product strategy. `--full-auto` is easy to understand and dangerous to normalize. It says: let the agent do everything. Permission profiles say something more precise: let the agent do the right set of things for this workspace, this command, and this trust level. For real teams, that is the only sustainable model. Good agent permissions should be boring: - read-only for audits - write access for narrow implementation - restricted network for dependency installs - explicit approval for package manager changes - stronger controls for production config The April changelog shows Codex moving toward that model. Permission profiles now round-trip across TUI sessions, user turns, MCP sandbox state, shell escalation, and app-server APIs. That consistency matters because the worst permission bugs happen at boundaries. ## 5. Plugins are becoming first-class April added and expanded plugin marketplace workflows in multiple places: - `codex marketplace add` - app-server support for installing plugin marketplaces - remote plugin install - marketplace upgrades - plugin-bundled hooks - hook enablement state - external-agent config import This is Codex moving toward an ecosystem model. Claude Code has had a cultural lead here because skills and plugins are simple to reason about: a `SKILL.md`, a folder, and a repeatable workflow. Codex is now building toward similar leverage, but with more app-server and marketplace infrastructure around it. For users, the important question is not "does Codex have plugins?" It is whether plugins become the place where durable team knowledge lives. The answer should be yes. If a team learns a repeatable workflow, it should not stay in someone's chat history. It should become a skill, plugin, command, or project instruction. That is how agent work compounds. April's plugin changes make Codex better suited for that kind of compounding. ## 6. GPT-5.5 is the new default mental model for hard Codex work OpenAI's April 23 Codex update says GPT-5.5 is available in Codex and is the recommended choice for most Codex tasks when it appears in the model picker. The changelog calls out implementation, refactors, debugging, testing, validation, and knowledge-work artifacts as especially good fits. The practical model split now looks like this: | Work type | Better Codex choice | |-----------|---------------------| | complex implementation | GPT-5.5 | | architecture or refactor planning | GPT-5.5 | | debugging and validation | GPT-5.5 | | lighter codebase exploration | GPT-5.4 mini | | supporting subagent work | GPT-5.4 mini | | usage-constrained long sessions | mini model where possible | This mirrors how many developers already route work manually: expensive model for judgment, cheaper model for exploration. The March 17 changelog entry for GPT-5.4 mini is useful context. OpenAI positioned it as a fast, efficient model for lighter coding tasks and subagents, with lower included-limit consumption than GPT-5.4. That matters because Codex is increasingly a multi-agent environment. You do not want every subagent burning your strongest model. ## 7. Pricing and usage are part of the product now The April 30 ChatGPT release notes introduced a new $100/month Pro plan and changed how Codex usage works across Plus and Pro. OpenAI positioned the $100 plan for longer, high-intensity Codex sessions, while Plus remains the steady day-to-day tier as the temporary Plus Codex promotion ends. That is the clearest signal yet that Codex usage is becoming a core subscription differentiator. For developers, the decision is no longer just "does Codex work?" It is: - How often do I run high-intensity sessions? - Do I need long single-day sessions or steady weekly usage? - Can mini models handle support work? - Is Codex replacing another paid coding tool or stacking on top of it? If Codex is your primary agent, the $100 Pro tier may become the real middle path between Plus and $200 Pro. If Codex is your backup agent, Plus may still be enough. If you run agents all day, the highest-usage tier is still the safer bet. For a broader budget view, see [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) and [AI coding tools pricing Q2 2026](/blog/ai-coding-tools-pricing-q2-2026). ## 8. The app is becoming more than code The April 16 Codex app update is easy to miss because it is broad, but it tells the biggest story. OpenAI described Codex as becoming a broader workspace for getting work done with AI. The update added or highlighted: - in-app browser verification - computer use for macOS app flows - chats that do not require a project folder - thread automations - task sidebar context - GitHub PR review inside the app - artifact previews for generated PDFs, spreadsheets, documents, and presentations - memories where available - remote connections rolling out in alpha - multiple terminals - menu bar and system tray support - multi-window support That is not just a coding terminal. That is an operator console. This is where Codex and Claude Code are diverging in interesting ways. Claude Code is still strongest as a terminal-native programmable agent. Codex is increasingly trying to be the desktop and cloud surface where many agent workflows meet: local code, remote worktrees, browser checks, PR review, docs, artifacts, and automations. If you live in the terminal, Claude Code still feels natural. If your work jumps between repo, browser, PR review, design docs, generated files, and scheduled follow-ups, Codex's app direction makes sense. ## What this means for your workflow Here is the practical workflow I would use after the April updates: ### Use Codex for verified frontend changes When a task has visible UI behavior, ask Codex to use the browser to verify it. ```txt Update the pricing page CTA copy, then open the local page in the in-app browser and verify the desktop and mobile layout. Fix any wrapping or overlap before you finish. ``` ### Use goals for compounding tasks For SEO, QA, docs, and maintenance, start with a goal instead of a one-off prompt. ```txt Goal: improve the AI coding tools pricing cluster. Review analytics signals, recent repo changes, and current internal links. Complete the five most meaningful improvements you can safely make today. Commit only your changes. ``` ### Use permission profiles by default Do not normalize full access for every task. Use tighter profiles for audits and broader profiles only when the task actually needs writes, network, or package-manager changes. ### Route models deliberately Use GPT-5.5 for hard judgment and implementation. Use mini models for exploration, summarization, and supporting subagents when quality risk is lower. ### Turn repeated wins into skills If Codex finds the same SEO issue, deployment issue, or content workflow more than once, write it down as a project skill or instruction. The April plugin and skills direction makes this more valuable, not less. ## Codex vs Claude Code after April The April changelog does not make Codex "better than Claude Code" in every workflow. It makes the distinction clearer. For the broader decision tree, use the [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) shoot-out after this change-by-change read. Pick **Codex** when: - you want app-level verification - you want cloud/local handoff - you want a managed desktop workspace - you want automatic approval review gates - you want browser and artifact workflows in one place - you are already paying for ChatGPT plans that include Codex Pick **Claude Code** when: - you want terminal-first control - you already have a strong `CLAUDE.md` and skills setup - you want deep local customization - you prefer explicit shell workflows - you rely heavily on community skills and plugins Pick **Cursor** when: - you want inline completion and IDE-native editing - you care more about visual diffs than background agents - you want the shortest path from thought to local code edit For the full head-to-head, read [Claude Code vs Codex App](/blog/claude-code-vs-codex-app-2026), [Cursor vs Codex](/blog/cursor-vs-codex), and [Claude Code vs Cursor vs Codex](/blog/claude-code-vs-cursor-vs-codex-2026). ## The real takeaway Codex is becoming an agent workspace, not just an agent. The April changelog adds features that serious users needed: persistent goals, browser verification, safer approvals, better permission profiles, stronger plugins, and clearer model routing. Those are not flashy demo features. They are the boring infrastructure that makes agents useful for daily engineering. That is the correct direction. The next question is whether OpenAI can make all of this feel simple. Codex now has the pieces: app, CLI, IDE extension, web, cloud execution, local worktrees, plugins, skills, automations, browser, computer use, and PR review. The product challenge is coherence. For developers, the move is straightforward: treat Codex as a serious daily tool, but use it with strong project instructions, explicit permissions, deliberate model routing, and verification loops. The teams that do that will get more value than the teams that keep prompting it like a chatbot with file access.

Codex /goal and Claude Managed Outcomes: The New Control Loops

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

There are two similar sounding directions to make long-running agents less flaky. - OpenAI's Codex CLI added `/goal` in version 0.128.0. - Anthropic introduced **outcomes** for Claude Managed Agents as a research preview. They are both about **keeping the loop going until quality is actually acceptable**, but they solve it at different layers. If you are here to choose a workflow, the short answer is: - Use **Codex `/goal`** when you want a coding agent to keep making progress inside a terminal session, especially across repo edits, tests, retries, and interruptions. - Use **Claude outcomes** when the output needs an explicit acceptance rubric, review trail, and measurable "done" state. - Use both when the work is long-running and high-stakes: Codex-style goal persistence for execution, then outcome-style rubrics for final quality checks. For adjacent decisions, read the broader [Codex vs Claude Code comparison](/blog/codex-vs-claude-code-april-2026), the [Claude Code vs Codex side-by-side page](/compare/claude-code-vs-codex), the [April Codex changelog analysis](/blog/codex-changelog-april-2026), and the [AI agent frameworks guide](/guides/ai-agent-frameworks-compared). If you are asking whether Codex can handle tasks beyond code, read [Codex as a general-purpose AI agent](/blog/codex-general-purpose-ai-agent). If cost is the deciding factor, start with the [pricing hub](/pricing). If you want to practice the execution side instead of just comparing control loops, the [Agentic Coding course](/courses/agentic-coding) covers decomposition, multi-agent workflows, and production agentic development patterns. ## What changed with `/goal` Codex's own changelog says 0.128.0 added **persisted `/goal` workflows** with app-server APIs, model tools, runtime continuation, and TUI controls to create, pause, resume, and clear goals ([OpenAI Codex changelog](https://developers.openai.com/codex/changelog#codex-cli-01280)). That sounds simple in a headline, but the interesting part is the implementation shape: - It is in the command loop itself, not in your prompt alone. - A goal is durable across restarts. - The TUI can control the cycle (`create`, `pause`, `resume`, `clear`) and the CLI can continue work without you typing follow-up prompts each turn. - The release note implies model/tool and UI surfaces were added together, which usually means this is productized as a command-state feature, not just a clever instruction hack. The older pattern was: send a goal, let the model act a bit, stop, send next command. `/goal` is trying to invert that pattern so it keeps iterating in one execution envelope until stop criteria are met. ## Why this matters operationally The old problem is usually one of **loop boundary leakage**: 1. You ask for a non-trivial task. 2. The agent does multiple shell/tool steps. 3. Either it runs out of budget or gets into a suboptimal partial path. 4. You do not have a clean way to continue from state without repeating context. A persisted goal narrows this by formalizing loop continuation and reducing "human re-entry overhead." ## Where Codex `/goal` likely shines From the release context and existing Codex command model: - **Terminal-native development workflows**: if you are doing hands-on repo work, compile checks, and iterative shell-driven repair, command-level persistence is a direct fit. - **Plan-mode and interruption semantics**: the same release also references plan-mode nudges and `/statusline`/`/title` editing during active turns, which points to a richer TUI-centered workflow control plane. - **Feature-flagged evolution**: the 0.128.0 bullet list reads like staged rollout and feature gating. In practice, that is good for enterprise operators who want controlled enabling. I read that as: `/goal` is primarily a **tooling-loop enhancement** around coding agent endurance. ## Claude outcomes: rubric-driven task closure Claude managed agents exposes outcomes as research preview, where you define what "done" looks like and the system works toward that target with a grader loop. The managed agents documentation says outcomes let you tell the agent what "done" looks like, then evaluate per-criterion grading in a separate context window until the outcome is satisfied or max iterations are hit ([Claude managed agents outcomes](https://platform.claude.com/docs/en/managed-agents/define-outcomes)). Key details in that page: - Outcomes are explicitly "Research Preview" and require the managed-agents preview beta header when used with the API. - A **rubric is required**, as markdown text or uploaded file. - The grader returns structured results per criterion and emits explicit outcome status (`satisfied`, `needs_revision`, `max_iterations_reached`, `failed`). - You can chain outcomes one after another in a session. This is not just "keep looping." It is **close-loop evaluation** with explicit quality criteria. ## Real comparison: control primitives Let's compare from a design perspective. ### 1) What is the stopping rule? - `/goal` (Codex): runtime/command-oriented termination via agent loop and manual controls (`pause`, `clear`, budget limits in feature context). It sounds like loop completion is driven by model judgment plus command state. - `outcome` (Claude): outcome status is externally graded against rubric criteria in separate context. That makes termination a function of measured rubric satisfaction. ### 2) Where does quality live? - `/goal` quality is implicit, shaped by your prompt and agent context. - outcomes quality is explicit, shaped by rubric design and evaluator output. ### 3) Operational friction - `/goal` integrates with existing Codex sessions and CLI continuity (especially useful when you already live inside terminal loop). - outcomes integrates with managed-agent sessions and Files API event stream, and uses event telemetry (`span.outcome_evaluation_*`) that is useful for observability and audit. ### 4) Infrastructure complexity - `/goal` is a command feature and likely lighter to adopt if you already standardize around Codex in a repo. - outcomes demands rubric infrastructure and managed-agent API headers, but gives better reporting for quality-critical workflows. ## Novel examples that reveal the difference ### Example 1: Large-scale migration with build validation **Use `/goal` when:** you need persistent CLI execution with many shell passes. - Goal text: "Migrate all API v1 clients to v2 and keep tests green." - Agent keeps running: search + patch + run tests + patch again. - Human intervention points: `pause`, `status`, final diff. This is the right shape when your objective is operational execution and tool orchestration speed. ### Example 2: Financial model generation from SEC filings **Use outcomes when:** you need objective quality checks. - Rubric includes explicit data source, assumption statement fields, forecast horizon, and file structure. - Agent writes output artifacts and grader checks each criterion. - Failure gives exact rubric gaps to revise. This is the right shape when acceptance is judgment-heavy and you need repeatability. ### Example 3: Product support playbook from a messy codebase Hybrid approach: - `goal`: first pass that extracts stack trace clusters and prepares candidate fixes. - `outcome`: second pass with rubric requiring reproduction steps, regression test, and evidence artifact links. This gives the endurance of `/goal` plus rubric-level correctness from outcomes. ## Common mistakes 1. **Treating `goal` as output quality control** `/goal` is excellent for keeping work moving, but without explicit criteria it can optimize for forward motion over quality nuance. 2. **Treating outcomes as "just autopilot"** Outcomes still depend on rubric design. Bad rubric = bad stopping decision. 3. **Ignoring token budgets / iteration caps** Codex has token/continuation limits in feature work; outcomes has max iterations and explicit `failed`/`max_iterations_reached` result states. 4. **Not version-gating** Outcomes is explicitly research preview. Plan for fallback runbooks. ## Practical migration map If you are currently on Codex-only loops, start with: - Enable and test `/goal` in staging workspace. - Measure average iterations, interruption frequency, and budget exhaustion events. - Add manual checkpoint artifacts after each successful loop. If you then add managed-agent workloads: - Define two rubric templates: a minimal "safety/format" rubric and a full "business quality" rubric. - Prefer rubric templates as versioned files in a session-level directory. - Emit outcome IDs and evaluation summaries to your telemetry store. If you are choosing where to start right now: - **Need immediate coding loop resilience in terminal sessions?** `/goal`. - **Need auditable deliverable quality in autonomous tasks?** outcomes. - **Need a broader tool choice first?** Start with [AI tool comparisons](/compare), [AI coding tools pricing](/blog/ai-coding-tools-pricing-2026), or [Claude Code vs Codex](/blog/codex-vs-claude-code-april-2026). ## So what's the real difference? This is the sharp distinction: - **Codex `/goal` = loop state as runtime control.** - **Claude outcomes = loop state as quality control contract.** They are converging, but they are not redundant yet. For teams building production automations, the highest-leverage stack is often both: 1. Use `/goal` for "keep going and recover from interruption." 2. Use outcomes when handoff quality must be measurable and rubric-traceable. ## Sources - OpenAI Codex changelog entry for 0.128.0 (persisted `/goal` workflows and related items): https://developers.openai.com/codex/changelog - OpenAI Codex docs hub: https://developers.openai.com/codex/ - Codex CLI slash commands overview: https://developers.openai.com/codex/cli/slash-commands - OpenAI Codex pricing: https://developers.openai.com/codex/pricing - Mintlify Codex slash command listing for command context: https://www.mintlify.com/openai/codex/features/slash-commands - Claude Managed Agents launch post: https://www.anthropic.com/news/claude-managed-agents - Claude managed agents define outcomes (research preview): https://platform.claude.com/docs/en/managed-agents/define-outcomes - Claude API pricing: https://platform.claude.com/docs/en/about-claude/pricing ## FAQ ### What is the difference between Codex /goal and Claude managed outcomes? Codex `/goal` is a **runtime control** feature built around persisted workflows, runtime continuation, and TUI controls for creating, pausing, resuming, and clearing goal state. Claude managed outcomes is a **quality control** feature that uses explicit rubrics to grade whether work meets acceptance criteria before stopping. Use `/goal` for persistent execution, outcomes for measurable deliverables. ### When should I use Codex /goal instead of Claude outcomes? Use Codex `/goal` when your task is terminal-native development work like migrations, test fixes, or repo refactoring where the primary need is durable continuation through repo edits and shell-driven repair cycles. If your task needs an explicit acceptance rubric or audit trail, use Claude outcomes instead. ### Can I use Codex /goal and Claude outcomes together? Yes, a hybrid approach is often the best choice for long-running, high-stakes work. Use Codex `/goal` for the execution phase where the agent needs to keep making progress across shell commands and test cycles. Then use Claude outcomes as a final quality gate with explicit rubric criteria. This gives you both execution endurance and measurable correctness. ### How do I migrate from Codex loops to Claude managed outcomes? Start by testing `/goal` in a staging workspace to measure iteration count, interruption frequency, and budget exhaustion. Add manual checkpoint artifacts after each loop. When adding managed-agent workloads, define rubric templates as versioned files: one minimal safety/format rubric and one full business quality rubric. Emit outcome IDs and evaluation summaries to your telemetry store. ### What are the limitations of Codex /goal? The main limitation is that `/goal` optimizes for forward motion, not output quality. Without explicit acceptance criteria, it can complete work that passes tests but misses quality nuance. It also has token and continuation limits that may halt complex tasks. For quality-critical workflows, pair `/goal` with a rubric-based quality check or use Claude outcomes. ### What are the limitations of Claude managed outcomes? Claude managed outcomes depends entirely on rubric design - a bad rubric leads to bad stopping decisions. It is also marked as research preview, so you should plan for fallback runbooks. The managed-agent API requires preview beta headers and has max iteration limits. When the grader returns `max_iterations_reached` or `failed`, you need a recovery path. ### Which is better for production automations? For production, the highest-leverage stack is often both: use Codex `/goal` for "keep going and recover from interruption" during execution, then use Claude outcomes when handoff quality must be measurable and rubric-traceable. This combines the execution resilience of `/goal` with the quality assurance of rubric-graded outcomes. ### How do Codex /goal and Claude outcomes compare on cost? The public docs do not provide a clean apples-to-apples price formula. Treat Codex `/goal` cost as the underlying Codex session and model usage, then check [OpenAI Codex pricing](https://developers.openai.com/codex/pricing) before estimating. Treat Claude outcomes as managed-agent usage plus outcome evaluation usage, then check [Claude API pricing](https://platform.claude.com/docs/en/about-claude/pricing). For budget-sensitive work, start with the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-2026) and the [pricing hub](/pricing).

DeepSeek V4 Changes the Coding Agent Cost Equation

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[DeepSeek](/blog/deepseek-v4-developer-guide) V4 is the most useful kind of model news: not a vague benchmark victory, but a pricing shock that changes what developers can afford to automate. The model was sitting on the Hacker News front page on May 2, 2026 through Simon Willison's writeup, [DeepSeek V4 - almost on the frontier, a fraction of the price](https://simonwillison.net/2026/Apr/24/deepseek-v4/). The HN thread was unusually practical. People were not only arguing about whether DeepSeek V4 is "frontier." They were comparing it against Claude Code limits, OpenAI pricing, Opus-quality planning, OpenRouter routing, privacy tradeoffs, and the actual cost of running long coding-agent sessions. That is the right frame. The point is not that DeepSeek V4 replaces Claude Opus, GPT-5.5, or [Gemini](/blog/gemini-deep-research) Pro everywhere. It probably does not. The point is that it makes a new stack shape rational: use cheaper strong models for wide, repetitive, or review-heavy work, then reserve expensive frontier models for the parts of software engineering where mistakes are costly. ## What Changed DeepSeek V4 shipped as two preview models: For cost context, read [AI Coding Tools Pricing Comparison 2026](/blog/ai-coding-tools-pricing-2026) alongside [The $400 Overnight Bill: Why Managed Agents Need FinOps Now](/blog/400-dollar-overnight-bill-agent-finops); together they separate sticker price from the operational habits that make agent work expensive. - **DeepSeek V4 Flash**: a 284B total parameter mixture-of-experts model with 13B active parameters. - **DeepSeek V4 Pro**: a 1.6T total parameter mixture-of-experts model with 49B active parameters. Both support a 1M token context window and use an MIT license. DeepSeek's own pricing page lists OpenAI-compatible and [Anthropic](/blog/anthropic-vs-openai-developer-experience)-compatible base URLs, JSON output, tool calls, chat prefix completion, and context caching. The price is the headline. DeepSeek's official docs list V4 Flash at $0.14 per million cache-miss input tokens and $0.28 per million output tokens. V4 Pro is listed at $1.74 per million input and $3.48 per million output before its current discount, with a temporary 75% discount through May 31, 2026. For developers, the more interesting number is cache-hit input pricing. DeepSeek lists cache-hit input for V4 Flash at $0.0028 per million tokens and discounted V4 Pro cache-hit input at $0.003625 per million tokens. That matters because [coding agents](/blog/what-is-an-ai-coding-agent-2026) reread the same project context constantly. ## Why Coding Agents Care About Cache Economics An agent run is not a single chat completion. It is a loop: 1. Read files. 2. Form a plan. 3. Edit code. 4. Run tests. 5. Read failures. 6. Patch again. 7. Summarize the diff. Most of that loop is repeated context. The repo conventions, API surface, relevant files, previous tool results, and test output come back again and again. If the provider can cache that prefix cheaply, long sessions get dramatically cheaper. That is why the HN comments around DeepSeek V4 were full of agentic coding math instead of generic benchmark takes. One commenter described the model as usable for frontend prototyping. Another said V4 Pro review runs were slower than Opus or GPT-5.5 but far cheaper. Others pushed back that reasoning-token usage can erase some of the advantage in pathological cases. All three can be true. Cheap tokens do not magically make a model better at planning. They do make it affordable to ask for more passes, more tests, more review, and more narrow agents working in parallel. ## The Right Use Cases Here is where I would try DeepSeek V4 first. ### 1. Second-pass code review Use your strongest model to implement. Then ask DeepSeek V4 Pro or Flash to review the diff against a checklist: - Did the change touch unrelated files? - Are there missing tests? - Are there obvious type holes? - Did the implementation violate project conventions? - Is there a smaller patch that would solve the same problem? This is exactly the kind of high-volume reasoning pass where cost matters. You want to run it on every PR, maybe multiple times, without caring about token burn. ### 2. Repo mapping Before giving an expensive model the task, use V4 Flash to build a map: - relevant entry points, - adjacent tests, - data models, - route handlers, - config files, - risky dependencies. Then pass the compact map to the frontier model. The cheaper model does the wide scan. The expensive model spends its budget on the actual decision. ### 3. Bulk documentation and migration chores DeepSeek V4 is a good candidate for repetitive work with reviewable output: - convert old docs to a new template, - add missing examples, - write migration notes, - generate test names, - summarize long issue threads, - draft release notes from merged PRs. These tasks are valuable, but they are not usually worth Opus pricing. They are perfect candidates for a cheaper model with a strict diff review gate. ### 4. Parallel speculative agents If one agent is expensive, you ask it for the answer. If agents are cheap, you can ask three agents for three different approaches and keep the best one. That sounds wasteful until the model price drops far enough. DeepSeek V4 pushes more teams toward that line. ## Where I Would Still Pay For Frontier Models I would not hand DeepSeek V4 the hardest planning work blindly. For large architectural migrations, security-sensitive rewrites, payment flows, auth, database migrations, or subtle production bugs, I still want the best model I can get. Not because benchmarks are everything, but because agent mistakes compound. A cheap bad plan can cost more than an expensive correct one. The comments around the HN thread also surfaced three practical cautions. First, some users see much longer thinking traces than they expect. If output or reasoning tokens balloon, the bill can surprise you. Second, data policy matters. Developers who are angry about code being used for training should be equally careful about where they send proprietary repo context. Third, "almost frontier" is not the same as "best at open-ended software work." A model can be strong at implementation and still weaker at long-horizon planning. ## The Stack I Would Try The practical architecture looks like this: ```text cheap model repo scan issue summarization test failure clustering second-pass review docs and release notes frontier model architecture decisions risky implementation security-sensitive changes final patch synthesis deterministic tools tests typecheck lint secret scanning diff constraints ``` Do not treat DeepSeek V4 as a replacement brain. Treat it as a cheaper worker in a larger engineering system. That is the deeper story behind the HN reaction. Developers are not just shopping for the best model. They are learning how to route tasks across a model portfolio. ## The Takeaway DeepSeek V4 makes coding agents cheaper in the places where agents are most token-hungry: long context, repeated review, bulk exploration, and parallel attempts. That does not remove the need for tests, review, or expensive frontier models. It changes where you spend them. The teams that get the most out of this release will not be the ones that switch everything to DeepSeek overnight. They will be the ones that separate their agent workflow into cost tiers: - cheap wide work, - expensive judgment work, - deterministic verification. That is how model pricing turns into engineering leverage. ## Sources - [Simon Willison: DeepSeek V4 - almost on the frontier, a fraction of the price](https://simonwillison.net/2026/Apr/24/deepseek-v4/) - [DeepSeek API docs: Models and Pricing](https://api-docs.deepseek.com/quick_start/pricing) - [Hacker News discussion](https://news.ycombinator.com/item?id=47977026)

Flue: The Agent Harness Framework and Why It Feels Different

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

Fred K Schott posted Flue on May 1, 2026 as a response to a familiar pain point: many teams are building powerful agent prompts, but they are still hand stitching runtime behavior. If you are running agent workflows in real repos, this is a useful signal. Flue is not trying to be another generic API wrapper. It is trying to be a harness-first framework for running agents. The idea is simple. You do not want every project to reinvent task orchestration, runtime control, session shape, and deployment glue. You want a framework to define those pieces once and let your team focus on behavior. That is exactly the pattern that made web frameworks like Next.js useful in the first place. You do not build your own server runtime every time, you build routes and logic. This is a practical builder-level comparison focused on runtime architecture, deployment tradeoffs, and migration implications. ## Who is Fred K Schott If you know him from Astro, this should feel familiar. Fred is a long-time open source builder with deep TypeScript and developer tooling experience, with a history tied to fast project bootstrap, compile-time developer experience, and community-first frameworks. He co-founded and helped scale the Astro ecosystem, and his move into Flue makes sense when you see the through line: reduce repetitive developer setup, standardize reusable patterns, and keep runtime behavior close to code. If you follow him on X, the launch post itself is short, direct, and very "build-tools-first." The same voice shows in the early framing for Flue: minimal abstraction where needed, opinionated structure where scale requires it, and clear affordances for CI and local execution. ## Why this matters now A lot of tooling in the agent stack still separates these concerns poorly: 1. Model and tool calls in one layer. 2. Tool orchestration in another layer. 3. Runtime decisions in an ad hoc layer built separately for each deployment. You end up with a lot of duplicated infrastructure in every stack. Flue puts harness concerns in one place and tries to make them portable. The official README frames it as the first agent harness framework and emphasizes that it is runtime agnostic and can be deployed on Node.js, Cloudflare, GitHub Actions, and GitLab CI/CD [Flue README](https://raw.githubusercontent.com/withastro/flue/main/README.md). The README language is blunt about being different from "yet another SDK," and that claim is testable if you look at how the examples are structured. ## What exactly is a harness, and why Flue calls itself that If you are already building agent systems, you likely treat this as obvious. Still, the boundary matters: - Prompting layer = how you ask a model to reason. - Tool layer = what the system can call. - Harness layer = how sessions start, what runs, how outputs are shaped, where execution happens, and what happens on failure. Most AI SDKs and graph frameworks are strong at the first two. Flue pushes the third to the center. In concrete terms, a harness should answer: - How do I route tasks? - How do I keep runtime consistent across local and CI? - How do I persist session outputs for the next run? - How do I move from shell behavior to HTTP behavior with minimal rewiring? Flue is opinionated exactly around these questions. ## Flue architecture primitives in practice From the docs and examples, a few patterns repeat. ### 1) Agent units with explicit behavior entry points Flue examples show explicit handlers and typed outputs. The result is not just "chat completion text." You are expected to return structured outcomes that downstream automation can trust. That sounds boring until you compare it with typical agent scripts where final output is still a natural language block. ### 2) Runtime target flexibility by design Flue advertises deployability across environments and runtime forms. If your team expects an agent to run from CLI and from CI with matching behavior, this is the value proposition. The practical impact is not just portability. It is consistency: - same task declaration syntax, - same logging format, - same session assumptions, - different environment details. ### 3) Execution model as an explicit part of code In Flue, sandbox strategy is first class. The docs include local and container style options, and the model says this is a tradeoff you define at runtime and project boundaries, not an implicit hidden behavior. If your workflows include low-risk metadata jobs and high-risk shell operations, this distinction is important. ### 4) AGENTS.md and skill-style context Flue includes markdown context conventions around AGENTS style files and project-local skill definitions. This does two things: - keeps agent behavior and docs near code, - avoids separate "agent memory store" systems for non-sensitive local behavior. You are effectively treating your repo as the control plane. ## Practical examples beyond the product docs The examples in launch posts are useful, but these are the examples teams usually care about. ### Example 1: CI recovery agent with bounded escalation You can model a deploy failure as an input event, then define a set of bounded recovery tasks: 1. collect failing workflows, 2. collect changed files, 3. check known flake patterns, 4. create one deterministic recommendation object. Then only escalate to a human when a threshold is crossed. This style is hard to maintain if each step uses a different orchestration style in each environment. A harness approach keeps this simpler. ### Example 2: Multi-team support routing agent Many teams split support across product, billing, and sales. A Flue style model can map incoming events to different agents with shared governance, and shared state contracts. This is where repo-local behavior and session output schemas get valuable. You can avoid rewriting the same classification rules across environments. ### Example 3: Migration assistant for monorepos In a monorepo, the same repository can have inconsistent release expectations. A harness framework helps you run the same recovery logic per package while still adapting to local tooling constraints. ### Example 4: Team-owned policy for secrets and approval Because Flue pushes runtime control into structured flows, you can create strict boundaries between model text and high risk execution. This supports a policy architecture where only approved paths are allowed at execution time. ## How Flue compares to popular alternatives I am not going to claim "best." I am going to compare what layer each stack solves first. ### Against OpenAI style SDKs and platform agents OpenAI gives excellent SDK and API tooling around model calls, tools, and session-like workflows. The [OpenAI Agents docs](https://platform.openai.com/docs/guides/agents-sdk/) and [agent JS docs](https://openai.github.io/openai-agents-js/guides/quickstart/) are strong for provider integration. Where the stack differs: - OpenAI stacks assume you are happy for the provider ecosystem to be the default runtime center. - Flue assumes you want to own the harness logic and run it wherever your repo needs it. If your stack is already provider-first and you want tighter OpenAI integrations, OpenAI stack makes sense. ### Against the Vercel AI SDK The Vercel AI SDK is heavily used in production web apps. As of recent npm stats, `ai` is in the tens of millions of weekly downloads and `@ai-sdk/openai` is also very large. It is excellent for model provider abstraction, streaming UI integration, and app-level usage patterns. The harness difference: - AI SDK: excellent as model and tool orchestration layer. - Flue: explicit harness and execution control layer. If your use case is mostly app-level model calls, AI SDK is still hard to beat. If your use case is multi-role execution with reproducible agent runtimes, Flue is stronger. ### Against LangChain and Deep Agents LangChain is a broad ecosystem and now a common choice for teams that want composability and long-lived memory tooling. A lot of teams use LangGraph for graph control and stateful flows. Deep Agents is the LangChain implementation that leans into more explicit agent runtime workflows and has been used in full stack web-agent systems, including strong middleware and handoff patterns. If that is your current mode, it can be very compelling. The key difference with Flue: - LangChain + Deep Agents stack gives strong graph composition and ecosystem depth. - Flue gives a harness-first pattern that is closer to "agent runtime as deployable unit." The right choice is less about who is technically richer on paper and more about where you want complexity to live. ### Against CrewAI style YAML orchestration CrewAI is practical for many Python-first teams and multi-agent role workflows. The template and crew model are simple to read. The tradeoff is the degree of TypeScript-native runtime portability is lower for teams that operate in JS/TS infrastructure first. Flue is TypeScript-first by design, so it naturally fits teams already shipping TS tooling. That is not a quality comparison. It is a fit comparison. ## Is Flue just rebranding, or a real shift? To avoid hype, here is how I test this question. ### Test 1: framework does the harness work for you If your team still writes custom runbook code for each environment, it is not a shift. If your team can move an agent flow from local to CI with mostly stable behavior, it is a shift. ### Test 2: session output can be consumed by other systems If most outcomes are still free-form prose, your orchestration stays fragile. If outcomes are structured and contract oriented, you can automate safely. ### Test 3: repo-local rules are first class If you still duplicate prompt and policy docs in dashboards or external stores, it is not yet a repo-owned harness. If you can keep policy inside codebase artifacts and review it with PRs, that is a real shift. ## Risks you should plan for Flue is not done with this story forever. The project is young enough that API churn and ecosystem maturity are real risk. 1. **Vendor and API churn** - expect breaking changes over time. - pin versions and run staged rollouts. 2. **Community breadth** - a smaller ecosystem now means fewer prebuilt integrations. 3. **Operational burden** - harness behavior can become opinionated, especially in bigger stacks. - you still need good monitoring and traceability. None of these are blockers if your team treats this as platform work and funds it as engineering debt reduction. ## A practical migration path if you are considering Flue You do not need a full rewrite. ### Step 1: isolate one bounded workflow Pick one task set with reliable input and output contracts. For example: triage a support queue. ### Step 2: define typed outcomes Create strict output objects and test them. This improves automation immediately. ### Step 3: run dual-stack Keep your existing runner and a Flue runner in parallel. Compare: - latency, - failure profile, - cost, - operational complexity. ### Step 4: move one policy layer at a time Start with sandbox and approval policy. Then move routing. Then move persistence. ### Step 5: only then scale to multiple environments If local and CI are stable in one area, then expand. ## Final take Flue matters not because it is flashy, but because it puts a real design decision in one place: harness first, not tool glue first. For teams already living in TypeScript and CI-heavy stacks, this is a practical path to reducing duplicated agent orchestration code. For teams that are provider-first with strong existing ecosystem dependencies, the gain can be marginal and the migration cost high. The bigger lesson for this whole industry is similar to every framework shift so far: value moves from "can it answer" to "can it run safely across environments with minimal extra glue." Flue is one of the clearest examples of that shift so far. ## Sources - Flue repository README: https://raw.githubusercontent.com/withastro/flue/main/README.md - Flue landing page: https://flueframework.com/ - OpenAI Agents SDK docs: https://platform.openai.com/docs/guides/agents-sdk/ - OpenAI Agents JS guide: https://openai.github.io/openai-agents-js/guides/quickstart/ - Vercel AI SDK package: https://www.npmjs.com/package/ai - Vercel AI SDK OpenAI provider: https://www.npmjs.com/package/%40ai-sdk/openai - Astro repository: https://github.com/withastro/astro - Fred K Schott on X: https://twitter.com/FredKSchott - Google ADK agents docs: https://adk.dev/agents/ - LangChain documentation: https://docs.langchain.com/oss/python/concepts/products - LangChain Deep Agents docs: https://docs.langchain.com/oss/javascript/deepagents/overview - Deep Agents reference: https://reference.langchain.com/javascript/modules/deepagents.html - Deep Agents package stats page: https://npmjs.com/package/deepagents - CrewAI installation docs: https://docs.crewai.com/en/installation

Flue and the Agent Harness Layer

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[Flue](https://flueframework.com/) is on Hacker News today with a clean pitch: "Agent = Model + Harness." That framing is more useful than another round of "agents are workflows" discourse. The model is no longer the whole product. For developer-facing agents, the valuable layer is increasingly the harness around the model: sandboxing, tools, skills, session state, typed outputs, triggers, deployment targets, and control over privileged commands. That is why Flue is interesting even if the first reaction is skepticism. The Hacker News thread had the obvious pushback: what problem does this solve, why not ask [Claude Code](/blog/what-is-claude-code-complete-guide-2026) to write the boilerplate, how is it different from Mastra, and why TypeScript again? Those are fair questions. They also point straight at the category. The serious agent stack is splitting into layers. ## The harness is the product surface Flue describes itself as a TypeScript framework for building agents with a built-in harness. The examples are not just chat completions. They show agents with webhook triggers, virtual sandboxes, mounted knowledge bases, session persistence, roles, typed result schemas, command definitions, local CI access, and remote [MCP](/blog/what-is-mcp) tools. That matters because a production agent is not a prompt. It is a controlled environment where a model can act. A useful agent framework has to answer boring questions: - Where does the agent run? - What files can it see? - Which tools are allowed? - Which secrets are hidden from the model? - What state persists between sessions? - What result shape is required? - What happens when the model loops? - How does the final artifact get inspected? Most AI SDKs make it easier to call a model. A harness framework tries to make it easier to operate the model. That distinction is the same pattern behind [ML Intern's domain-agent loop](/blog/ml-intern-domain-agents) and [Open Design's artifact wrapper](/blog/open-design-agent-design-engine). The wrapper is where the product starts to have opinions. ## Why "just generate the boilerplate" is not enough The strongest skeptical take is that a [coding agent](/blog/what-is-an-ai-coding-agent-2026) can already generate the scaffolding for a support bot, triage bot, or CI agent. So why introduce a framework? That argument is right for demos and wrong for repeatable systems. Boilerplate is only painful once. Operational consistency is painful every day. If every team asks an agent to freestyle its own sandbox layer, command policy, result validation, trace format, and deployment glue, the organization gets a pile of almost-compatible one-off agents. They may work, but they are hard to audit, hard to reuse, and hard to compare. A harness framework creates a standard shape: - agents live in known files - skills and context are discoverable - prompts can return typed results - privileged commands can be wrapped - local and remote sandboxes share an interface - deployment targets are part of the framework contract That is the part you do not want a model inventing differently every time. The model can still write the agent logic. The framework should own the dangerous edges. ## The TypeScript bet is pragmatic, not sacred The other obvious complaint is that agent infrastructure does not need to be TypeScript. True. Go, Python, Rust, and C# all have strong claims here. But TypeScript has one practical advantage: the agent product surface is already web-shaped. Webhooks, dashboards, auth, background jobs, edge deployments, schema validation, SDKs, and frontend previews all live comfortably in the TypeScript ecosystem. Flue's pitch is not "TypeScript is the only good agent language." It is closer to "agent applications are becoming web applications with a model-driven worker inside." That is a credible lane. The risk is that JavaScript fatigue makes every framework look like more framework. The way around that is not louder marketing. It is sharper defaults, smaller examples, and evidence that the harness removes real operational work. ## The key design choice is control The most important examples in the README are not the flashy ones. They are the command-control examples. Flue shows a CI triage agent where privileged CLIs such as `gh` and `npm` are connected through command definitions. Secrets are kept in trusted code, not dumped into the model context. Commands can be granted to a specific skill call. Results can be schema-validated. That is the right direction. The next wave of agent systems will not be trusted because the model is polite. They will be trusted because the harness narrows what the model can do, records what happened, and returns structured evidence. That fits the broader lesson from [agent swarms needing receipts](/blog/agent-swarms-need-receipts): orchestration without reviewable outputs becomes theater fast. Agents need autonomy, but they need bounded autonomy. The harness is where those bounds live. ## The opposing view The fair opposing view is that this category can become premature abstraction. If your agent is one script that summarizes an issue and posts a comment, a full framework may be too much. You can use the model provider SDK, a queue, a few shell commands, and a JSON schema. There is also a real risk that [agent frameworks](/blog/ai-agent-frameworks-compared) compete on concepts instead of outcomes. Roles, skills, sandboxes, sessions, traces, MCP tools, and deploy targets can sound like progress while hiding the simple question: did the agent complete the task more reliably? That is the bar Flue and similar frameworks have to clear. The useful version is not "Next.js for agents" as a slogan. The useful version is: - fewer hand-rolled wrappers - clearer command permissions - repeatable deployment - better state handling - typed artifacts - easier review - lower cost per agent session If those do not show up, the framework is decoration. ## What builders should copy Even if you do not adopt Flue, the pattern is worth stealing. When building an internal or external agent product, define the harness explicitly: 1. Trigger: what starts the agent? 2. Workspace: what can it read and write? 3. Tools: what operations are available? 4. Secrets: what never enters model context? 5. Skills: what reusable procedures guide the run? 6. State: what survives between sessions? 7. Result: what structured artifact must come back? 8. Evidence: what logs, diffs, traces, or screenshots prove the work? That list is more important than the framework brand. The same structure applies to code review agents, support agents, documentation agents, QA agents, and database migration agents. A model is useful when it is inside a workflow that constrains and verifies it. ## My take Flue is early, and the skepticism is healthy. But the phrase "agent harness" is a good handle for where the category is going. The model layer is powerful and increasingly interchangeable. The product value is moving into the harness: the controlled runtime, the workflow contract, the artifact shape, and the operational guardrails. That is why Flue is worth watching. Not because every team needs a new TypeScript framework tomorrow. Because serious agents need more than prompts, and the harness is where serious starts.

GitHub Copilot Coding Agent and CLI: Why GitHub Is Back in the Agent Race

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

GitHub Copilot spent years as the default AI coding assistant. Then the market shifted. Cursor made AI-native editing feel normal. [Claude Code](/blog/what-is-claude-code-complete-guide-2026) made terminal agents feel inevitable. Codex pushed asynchronous coding into ChatGPT and desktop workflows. GitHub's response is now clear: Copilot is becoming an agent platform inside GitHub. That is a bigger deal than another chat sidebar. ## The Coding Agent Changes the Shape GitHub's [coding agent announcement](https://github.com/newsroom/press-releases/coding-agent-for-github-copilot) moved Copilot into asynchronous work. Instead of only asking for edits in the IDE, you can assign a GitHub issue to Copilot or start work from Copilot Chat in VS Code. The agent then works in the GitHub flow, pushes commits to a draft pull request, and exposes session logs so developers can review and iterate. For the larger agent workflow map, read [GitHub Copilot in 2026: Still Worth It for TypeScript Developers?](/blog/github-copilot-guide) and [AI Coding Tools Pricing in Q2 2026: What Actually Changed and Where Costs Surprise Teams](/blog/ai-coding-tools-pricing-q2-2026); they give the architecture and implementation context this piece assumes. That is the GitHub-native version of agent delegation. Claude Code starts from the terminal. [Codex](/blog/openai-codex-guide) starts from an agent workspace. Copilot starts from the issue and pull request workflow. For teams already living in GitHub, that is powerful. The agent does not need to invent a task surface. Issues, branches, PRs, reviews, Actions, code owners, and permissions already exist. ## Copilot CLI Makes the Terminal Strategic The second shift is [Copilot CLI general availability](https://github.blog/changelog/2026-02-25-github-copilot-cli-is-now-generally-available/). GitHub describes it as a terminal-native coding agent that can plan, build, review, remember across sessions, edit files, run tests, and iterate until the job is done. That is not classic Copilot. That is a direct response to Claude Code, Codex CLI, [Gemini CLI](/blog/best-cli-tools-for-ai-development-2026), and the broader terminal-agent wave. The interesting detail is extensibility. Copilot CLI ships with GitHub's MCP server built in, supports custom MCP servers, plugins, and markdown-based agent skills. Skills can work across Copilot [coding agent](/blog/what-is-an-ai-coding-agent-2026), Copilot CLI, and VS Code. That gives GitHub a cross-surface agent story: - Issue to coding agent - Terminal to Copilot CLI - Editor to VS Code - MCP to external tools - Skills to reusable workflows This is the shape every serious coding assistant is converging on. ## Model Choice Is Becoming Table Stakes GitHub is also moving faster on models. The [GPT-5.4 Copilot changelog](https://github.blog/changelog/2026-03-05-gpt-5-4-is-generally-available-in-github-copilot/) says GPT-5.4 is rolling out in Copilot for Pro, Pro+, Business, and Enterprise users, with improved performance on real-world, agentic, multi-step, tool-dependent coding work. Copilot CLI also advertises access to models from Anthropic, OpenAI, and Google depending on plan and availability. That matters because developers no longer want a single hidden model. They want to pick the right model for the task: - Fast cheap model for small edits - Strong reasoning model for architecture - Codex model for long repo work - Claude model for nuanced refactors - Gemini model for large-context exploration The tool layer matters, but model routing is becoming part of the product. ## Where GitHub Has a Real Advantage GitHub's advantage is not that its agent will always be smarter than every other agent. The advantage is that it owns the workflow graph around code. GitHub already has: - Issues - Pull requests - Reviews - Actions - Branch protection - Code scanning - Security alerts - Repository permissions - Organization policy - Billing and audit trails That makes it easier for Copilot to become acceptable inside larger companies. A terminal agent may be better for an individual developer. A GitHub-native agent may be easier for an organization to govern. This is why the Copilot coding agent matters even if you personally prefer Claude Code or Codex. It makes asynchronous agent work legible to engineering managers, security teams, and platform teams. ## Where It Still Needs to Prove Itself The risk is quality and cost. As agents move from autocomplete to long-running tasks, pricing gets harder. A quick prompt and a multi-hour repo task do not cost the provider the same thing. GitHub has already been shifting the Copilot product toward premium requests, AI credits, and model-specific usage controls. The second risk is review burden. If the agent opens a draft PR that still takes a senior engineer an hour to understand, it did not save enough time. The win condition is not "agent made a PR." The win condition is "agent made a reviewable PR with tests, rationale, and small enough scope." Teams should evaluate Copilot coding agent on: - PR size - Test quality - Session logs - Ability to incorporate review feedback - Respect for repo conventions - Security posture - Cost per accepted change ## The Competitive Map Here is the simple positioning: | Tool | Best surface | |------|--------------| | Claude Code | Local terminal orchestration | | OpenAI Codex | Agent workspace and managed coding tasks | | GitHub Copilot | GitHub-native issue to PR workflow | | Cursor | AI-native IDE editing | | Gemini CLI | Free large-context terminal work | Copilot is not trying to become Cursor. It is trying to make GitHub itself agentic. ## Keywords to Watch The GitHub search cluster is heating up: - GitHub Copilot coding agent - Copilot CLI - Copilot agent mode - GitHub coding agent - Copilot MCP - Copilot skills - GPT-5.4 Copilot - Copilot coding agent vs Claude Code If you are building content around AI coding in 2026, this cluster deserves its own pillar. GitHub has distribution, enterprise trust, and the pull request workflow. That is enough to keep Copilot in the race even as specialized agents get better.

jcode and the Coding Agent Harness Wars

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[jcode](https://github.com/1jehuang/jcode) is trending on GitHub with a very specific pitch: a next-generation coding agent harness built for multi-session workflows, customizability, and performance. The README leads with numbers most agent tools avoid: memory use, time to first frame, time to first input, and extra RAM per added session. That is the interesting part. Most coding-agent launches compete on intelligence, model support, and workflow demos. jcode competes on the physics of running a lot of agent sessions at once. That may sound narrow. It is not. If agents become normal development infrastructure, performance stops being a nice detail and becomes product strategy. ## Coding agents are becoming runtimes The first generation of [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026) felt like smart chat boxes connected to a repo. The next generation feels more like local runtimes: - multiple sessions - persistent memory - embeddings - file watching - background work - terminals - tool permissions - project context - replayable conversations - model routing Once you have that shape, resource use matters. A single agent session can be expensive but tolerable. Ten sessions across a large repo, each with state, tools, embeddings, and a live UI, is a different operating model. That is where jcode's README is making a concrete claim. It frames performance as an enabler for multi-session work, not as benchmark theater. This connects directly to [overnight agent workflows](/blog/overnight-agents-workflow). If you want agents running in parallel while you sleep, you need more than good prompts. You need low-friction session management and cheap enough runtime overhead to leave work in progress. ## The harness layer keeps getting clearer jcode calls itself a coding agent harness. That is the same language showing up in [Flue's agent harness framing](/blog/flue-agent-harness-layer), but aimed at a different surface. Flue is about programmable agents you can deploy. jcode is about the local coding-agent environment itself. The common thread is that people are no longer satisfied with "model plus shell." They want a harness that owns: - how sessions start - how context persists - how tools are exposed - how many jobs can run - how memory scales - how fast the UI responds - how easy it is to customize behavior That is where agent products are becoming infrastructure products. The model can write code. The harness decides whether that coding loop is ergonomic enough to use all day. ## Performance is a UX feature Agent speed is usually discussed as model latency. That is only part of the experience. Developer tools also have local latency: - launch time - terminal responsiveness - session switching - indexing overhead - memory growth - extra cost per concurrent task - how quickly the tool accepts the next instruction When those are slow, developers stop treating the agent as a working environment and go back to one-off prompts. jcode's emphasis on time to first frame and time to first input is a useful reminder that [coding agents](/blog/what-is-an-ai-coding-agent-2026) inherit expectations from terminals and editors, not just chat apps. If the tool feels heavy before the model even starts thinking, it loses trust. That is especially true for agent workflows where the human is supervising many tasks. A slow control surface makes parallelism feel expensive, even when the model work is useful. ## The opposing view The fair skeptical read is that local performance does not matter if the model is still the bottleneck. If a task takes ten minutes because the model explores, edits, tests, and revises, shaving hundreds of milliseconds from startup can sound irrelevant. That skepticism is partly right. For one-off deep tasks, model quality, tool reliability, and test feedback matter more than interface launch time. But multi-session workflows change the math. When an agent tool becomes something you keep open, reuse, script, and fan out across tasks, overhead compounds. Memory per session matters. Startup time matters. Switching cost matters. The cost of leaving ten agents alive matters. The mistake is treating performance as a substitute for reliability. It is not. Performance is the floor that lets reliability work at scale. ## Why this matters for product builders If you are building an agent product, jcode points at a set of questions worth asking early: - How much memory does an idle session use? - How much does each additional session cost? - Can users keep multiple tasks alive without relaunching everything? - Is project context shared, copied, or recomputed? - Can the agent resume without rebuilding its whole mental model? - Does the tool feel instant before the model call starts? - What happens when a session stalls? These questions are not as exciting as "which model is best?" They are more durable. Model rankings will keep changing. Runtime ergonomics, state management, and session economics will matter regardless of which model is winning this month. That is also why [the agent reliability cliff](/blog/the-agent-reliability-cliff) is not just a model problem. Reliability lives in the surrounding system: the harness, the receipts, the evaluation loop, and the cost of retrying. ## The benchmark trap There is one caution. Agent-tool benchmarks can become marketing fast. Memory numbers depend on platform, configuration, embeddings, repo size, plugins, UI state, and whether a session is doing real work. Startup numbers are even easier to overfit. So the useful conclusion is not "jcode is definitively faster than every other tool in every condition." The useful conclusion is that jcode is competing on the right axis. Agent tools should publish resource behavior. They should explain idle cost, active cost, multi-session cost, and what features change the numbers. Developers can handle nuance. They just need the facts. ## My take jcode is interesting because it treats the coding agent as a long-lived developer runtime instead of a one-shot assistant. That is where the category is going. The winner will not be the tool with the loudest demo. It will be the tool that can keep many useful agent loops alive, make them cheap to supervise, preserve context without bloat, and return evidence that the work actually happened. Performance alone will not make an agent trustworthy. But without performance, [multi-agent workflows](/blog/building-multi-agent-workflows-claude-code) stay theoretical. That is why jcode is worth watching. It is a reminder that the coding-agent wars are not only about models. They are about harnesses, session economics, and the developer experience around sustained delegation.

lib0xc Is the Opposite of Rewrite Culture

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[lib0xc](https://github.com/microsoft/lib0xc) hit Hacker News today with a refreshingly unfashionable pitch: make C safer by codifying better standard-library-adjacent APIs. Not "rewrite everything in Rust." Not "pretend C can become fully memory safe." Not "ship a grand new language." Just a set of C11/GNU-extension APIs that make existing systems code less dangerous: static bounds, safer integer conversions, cursor-based formatting, context pointers, queue macros with bounds-safety annotations, allocation helpers, logging, unit tests, and compatibility with Clang's `-fbounds-safety` extensions. That is a useful counterweight to the current AI coding mood. AI makes rewrites feel cheaper. It is now easier than ever to ask an agent to port a subsystem, translate a library, or produce a replacement implementation. Sometimes that is the right call. Often it is just a faster way to create new risk. lib0xc is interesting because it takes the opposite stance: improve the codebase you actually have. ## What lib0xc is trying to do The [README](https://github.com/microsoft/lib0xc) is explicit about the scope. C cannot be made completely type-safe or bounds-safe at the language level, but common C usage can be made safer. For the security frame around this, see [OpenAI Codex Cloud Security Playbook 2026: Internet Access, Prompt Injection, and Safe Defaults](/blog/openai-codex-cloud-security-playbook-2026) and [Open Source Has a Bot Problem: Prompt Injection in Contributing.md](/blog/prompt-injection-open-source); both focus on the places where agent autonomy needs explicit boundaries. The project goals are practical: - enable aggressive warnings and `-Werror` - provide familiar APIs that look like standard-library replacements - embrace static bounds - support Clang `-fbounds-safety` - document and test patterns that have circulated informally for years - make safer API contracts easier to use than unsafe ones That last goal is the whole story. Good safety work changes the default path. The examples are not flashy. A bounded `CURSOR` tracks remaining buffer space during formatting. A `context_t` exports and imports typed context pointers with size checks. Integer conversion helpers trap on overflow instead of silently truncating. Portable printf helpers avoid format-specifier footguns. This is the texture of real systems maintenance. Small contracts. Fewer unchecked assumptions. Better compiler leverage. ## Hacker News split along the right line The HN response was positive, but not naive. Some commenters saw obvious low-hanging fruit: safer C and C++ interfaces could remove a large class of spatial memory problems if teams actually used them. Others liked the incremental adoption story and the `-fbounds-safety` angle. The skepticism was just as important. One commenter asked whether Microsoft uses this in production or whether it is a side project. Another noted that a Microsoft project depending on GNU extensions and not supporting MSVC or Windows is surprising. The sharper objection was philosophical: this can look like an excuse to keep using unsafe languages instead of moving to safer ones. That objection deserves respect. If you are starting a greenfield service, "use safer APIs in C" is often weaker advice than "do not write this in C." Rust, Zig, Swift, Go, Java, C#, and other safer options exist for many problem shapes. But that does not answer the installed-base problem. Large C and C++ codebases are not going away because a migration memo says they should. Operating systems, embedded stacks, media pipelines, databases, runtimes, device software, and old infrastructure will keep carrying C for a long time. For those codebases, incremental safety is not a compromise. It is the work. ## Why this matters more in the agent era [AI coding agents](/blog/what-is-an-ai-coding-agent-2026) change the risk profile of old systems code. They make it easier to touch unfamiliar files. They make it easier to produce large diffs. They make it easier to translate patterns without understanding every invariant. They also make it easier to accidentally paper over a warning, widen a cast, or copy an unsafe idiom because it appeared elsewhere in the codebase. That means old C code needs stronger rails, not just stronger reviewers. Libraries like lib0xc are one form of rail. Compiler warnings are another. Bounds-safety annotations are another. Tests, static analysis, fuzzing, and narrow review hooks are all part of the same control layer. The AI-era version of C safety is not: "Ask an agent to rewrite it." It is: "Make the safe path obvious enough that agents and humans both fall into it." When an agent edits a codebase with safer APIs, high warning levels, checked conversions, and tests, the environment pushes back. The agent can still be wrong, but wrong changes are more likely to fail loudly. That is what you want. ## The adoption test The real question for lib0xc is not whether the API is clever. The question is whether a team can adopt one piece without accepting the whole worldview. Incremental adoption wins when a developer can say: - use cursor formatting in this module - replace unsafe integer casts here - add bounds annotations around this buffer boundary - turn on one more warning class - add tests around the safer wrapper If adoption requires a rewrite, the library loses its main advantage. The README is at least aiming at the right shape: familiar names, drop-in replacements where appropriate, no allocator assumption for most APIs, POSIX static library builds, and support for macOS and Linux on arm64 and x86_64. The gaps matter too. Windows and MSVC support are obvious questions. GNU extensions are a pragmatic choice, but they narrow the adoption path. If the project is meant to influence industrial C, those constraints need a clear story. ## What AI tool builders should learn from it This is not just a C post. It is a lesson for [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026). Agents work better when codebases expose safer primitives. If a repo has no conventions, no helper APIs, no strict warnings, no tests, and no reviewable contracts, an agent is forced to infer too much from ambient code. If a repo has well-named primitives, tight APIs, and loud failure modes, the agent has something to grab onto. That applies across stacks: - React apps need design-system components instead of one-off styling. - Backend services need typed clients instead of raw fetch calls everywhere. - Database code needs migration helpers and query boundaries. - Infra repos need modules with policy baked in. - C code needs safer standard-library-adjacent APIs. The pattern is the same. Make the correct move easier than the dangerous move. AI does not remove that engineering work. It makes that engineering work more valuable. ## My take lib0xc is not a Rust killer. It is not a full answer to memory safety. It is not even trying to be. That is why it is useful. The practical world is full of code that cannot be rewritten this quarter, and maybe should not be rewritten at all. Those systems still need safer APIs, better warnings, static bounds, fewer silent casts, and tests that encode the local contract. In 2026, the boring safety layer matters more because more code will be touched by agents, junior developers, generators, and rushed migration work. The strongest AI-era engineering move is not always a rewrite. Sometimes it is making yesterday's codebase harder to misuse tomorrow.

Long-Running Agents Need Harnesses, Not Hope

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The dream version of agents is simple: give the task, close the laptop, wake up to a clean pull request. The real version is messier. The agent gets stuck on a missing environment variable. A test hangs. A package install fails. The browser never opens. The database seed is stale. The model keeps retrying the same command. The diff is technically correct but unreviewable. That is not a model problem alone. It is a harness problem. Long-running agents need infrastructure around them. The model is only one piece. The harness is what gives the run shape: task queue, workspace, tools, logs, checkpoints, budget, verification, and final review. For the reliability math, read [the agent reliability cliff](/blog/the-agent-reliability-cliff). For debugging runs after they fail, read [how to debug AI agent workflows](/blog/debug-ai-agent-workflows). ## What a Harness Does An agent harness is the system that wraps the model and the tools. It answers practical questions: - Where does the task come from? - What repo or workspace does the agent get? - Which tools are allowed? - Where do logs go? - How are secrets scoped? - What counts as done? - How are [costs](/blog/ai-coding-tools-pricing-comparison) capped? - What happens when a step fails? - How does a human review the result? Without a harness, a long-running agent is just a chat session with a lot of rope. ## The Minimum Viable Harness For coding work, the minimum useful harness has seven parts. **1. A task contract.** The task should include the goal, constraints, acceptance criteria, file boundaries, and verification commands. Vague tasks produce vague diffs. **2. A scoped workspace.** The agent should work in a repo, branch, sandbox, or worktree with clear boundaries. It should know what it can edit and what it should leave alone. **3. Tool policy.** The harness should define safe reads, safe writes, risky commands, denied commands, network access, and approval gates. **4. Persistent logs.** Every command, tool call, browser action, and test result should be captured. If the run fails, you need the transcript. **5. Checkpoints.** Long tasks should save state after meaningful milestones: plan accepted, implementation done, tests passing, review complete. **6. Verification.** The harness should run the actual checks that prove the task is done: tests, lint, typecheck, browser smoke, API probe, screenshot, or deploy health route. **7. Final receipt.** The output should say what changed, what passed, what failed, what remains risky, and where to inspect the diff. That is the baseline. Anything less is a demo. ## The Cost Cap Matters Long-running agents fail economically before they fail technically. A stuck loop can burn tokens for an hour. A cloud agent can keep a sandbox alive while making no progress. A browser session can collect screenshots and logs until the context window is useless. The harness should track: - elapsed time - model tokens - tool calls - retries - repeated command patterns - step count - sandbox runtime Then it should stop the run when the budget is exhausted or progress stalls. This is the practical side of agent FinOps. You do not need perfect accounting. You need enough telemetry to catch runaway work before the invoice does. ## Verification Is Not Optional Agents are very good at declaring victory. That is why the harness should decide what done means. If the task says "fix the checkout bug," the final answer is not enough. The harness should require the checkout test, the API route probe, or a browser flow through the checkout UI. For frontend work, that might mean: ```text pnpm typecheck pnpm test checkout open browser complete checkout flow capture screenshot check console errors ``` For backend work: ```text run focused unit tests run migration dry-run hit health endpoint inspect logs verify no unexpected schema drift ``` The exact checks vary. The principle does not: long-running agents need external proof. ## The Human Review Layer The harness should not remove the human. It should move the human to the right point. Humans should review: - task interpretation - final diff - security-sensitive changes - database migrations - production deploys - surprising behavior - failed verification Humans should not babysit: - reading files - running tests - retrying installs - collecting logs - summarizing obvious errors That is the division of labor that makes agents useful. ## The Bottom Line Long-running agents do not become reliable because the model got smarter. They become reliable because the system around the model got more disciplined. The harness is the product. It is what turns an impressive demo into a repeatable workflow. If your agent cannot show the task contract, logs, checkpoints, verification, cost, and final receipt, it is not ready to run while you sleep. ## Sources - Anthropic: [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code) - Anthropic Engineering: [Claude Code auto mode](https://www.anthropic.com/engineering/claude-code-auto-mode) - DevDigest: [The Agent Reliability Cliff](/blog/the-agent-reliability-cliff) - DevDigest: [How to Debug AI Agent Workflows](/blog/debug-ai-agent-workflows)

ML Intern Shows Where Coding Agents Are Heading: Domain Tools, Not Generic Chat

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

One of the strongest GitHub trending signals today is [huggingface/ml-intern](https://github.com/huggingface/ml-intern): an open-source ML engineer that reads papers, trains models, and ships ML code using the Hugging Face ecosystem. That description sounds like a big claim. The interesting part is more specific. ML Intern is not trying to be a generic coding assistant with a Hugging Face logo on it. It is a domain agent. Its loop is shaped around ML work: papers, datasets, models, repositories, cloud compute, Hub uploads, and session traces. That is where serious [coding agents](/blog/what-is-an-ai-coding-agent-2026) are heading. The first wave of [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026) asked: "Can the model edit files?" The next wave asks: "Can the model operate inside the actual domain system where the work happens?" For ML engineering, that system is not just a repo. It is papers, datasets, experiment runs, model cards, metrics, jobs, GPUs, evaluation artifacts, and a public or private Hub history. ## What ML Intern actually adds The [README](https://github.com/huggingface/ml-intern) describes ML Intern as a CLI agent with deep access to Hugging Face docs, papers, datasets, repositories, jobs, local tools, planning, MCP servers, and model provider routing through LiteLLM. For the larger agent workflow map, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they give the architecture and implementation context this piece assumes. It supports interactive mode: ```bash ml-intern ``` And headless mode: ```bash ml-intern "fine-tune llama on my dataset" ``` It can use OpenAI or [Anthropic](/blog/anthropic-vs-openai-developer-experience) models, take an HF token, use a GitHub token, and run for a configurable number of iterations. The most important detail is not the command. It is the trace model. Every session can be uploaded to a private Hugging Face dataset in [Claude Code](/blog/what-is-claude-code-complete-guide-2026) JSONL format, which the HF Agent Trace Viewer can inspect. The default dataset is private and tied to the user. The user can opt out, override the destination, or make traces public. That turns an agent run into a reviewable artifact. For ML workflows, this is not a nice-to-have. It is the difference between "the agent trained something" and "here is the run history, tool sequence, model response stream, and artifact trail." ## The trend is domain compression Generic agents have to learn the shape of every job from scratch. Domain agents cheat in the right way. They bundle the boring context: - where docs live - which APIs matter - how datasets are named - how jobs are launched - how artifacts are uploaded - which failures repeat - what a good trace looks like - when approval is required That compression matters more than a slightly better prompt. An ML agent that knows the difference between a dataset card, a model repo, a paper, a training job, and an evaluation artifact can do better work than a generic assistant that only sees a folder and a vague request. The same pattern is showing up across developer tools. Cloud agents know deployment platforms. IDE agents know worktrees and diagnostics. Terminal agents know tests and shell history. Browser agents know page state and interactions. Skills packages encode local process. The winning interface is not one universal chat box. It is a narrow agent loop with enough domain tools to be useful and enough receipts to be trusted. ## The hard part is not autonomy The README includes a maximum-iteration loop, approval checks, a tool router, context management, session uploads, and a doom loop detector. That last piece is more important than it sounds. Long-running agents fail in boring ways: - repeating the same command - searching instead of deciding - editing without validating - chasing a transient error - filling context with stale observations - making hidden assumptions about credentials - producing a final answer without a useful artifact ML makes those failures expensive. A bad web app diff wastes a few minutes. A bad training job wastes GPU budget, dataset time, and human attention. So the product surface has to include controls that interrupt bad loops. That means approvals, iteration limits, traces, notifications, private-by-default logs, and a clear way to inspect what happened. This is where ML Intern is more interesting than a demo. It is built like an operations loop, not just a prompt wrapper. ## The opposing view The fair skeptical read is simple: ML engineering is too empirical for an agent to "ship models" reliably. That skepticism is right if the agent is treated as an oracle. Reading a paper, choosing a method, preparing data, launching training, interpreting results, and deciding whether a model is good enough are not one-shot tasks. They involve judgment, failure, and iteration. But that is not an argument against domain agents. It is an argument against hiding the loop. The useful version of ML Intern is not "press button, receive model." It is "delegate a bounded ML task, get back code, runs, traces, errors, and artifacts that a human can inspect." That is a much more credible bar. In that frame, the agent is closer to a junior ML engineer with a very fast toolbelt than a magic model factory. It can read, implement, run, and report. The human still owns the experimental judgment. ## What builders should copy If you are building a domain-specific coding agent, copy the shape, not the branding. Start with a tight domain: - ML engineering - database migrations - security review - frontend accessibility - infra cost tuning - test triage - documentation maintenance Then give the agent first-class tools for that domain. Not just shell access. Real domain operations. For ML, that means datasets, papers, model repos, compute jobs, and traces. For security, it might mean SARIF, dependency graphs, secret scanners, policy files, and review comments. For database work, it might mean schema diffs, migrations, query plans, and sampled failures. Finally, make receipts unavoidable. The final output should include: - what changed - what ran - what failed - what artifact was produced - what needs human judgment That is the difference between a toy agent and a teammate you can route work to. ## My take ML Intern is part of a bigger shift: agents are moving from general-purpose coding chat into domain-specific operating loops. That is good. The generic agent category is crowded and increasingly hard to evaluate. Domain agents are easier to judge because they either complete the workflow or they do not. They either leave usable traces or they do not. They either understand the tools of the trade or they do not. For ML engineering, a useful agent has to live where ML work lives: papers, datasets, jobs, model repos, and evaluation trails. That is why ML Intern is worth watching. The headline is "open-source ML engineer." The deeper signal is that the next useful coding agents will be narrower, tool-rich, and receipt-heavy.

One Tool Beats Ten Endpoints

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The fastest way to make an agent worse is to give it too many tools. That sounds backwards. Agents need tools. Tools are what make them agents instead of chatbots. But most tool surfaces are designed by copying an existing REST API: - `getUser` - `listUsers` - `createTicket` - `updateTicket` - `attachFile` - `sendMessage` - `listMessages` - `searchMessages` That looks clean to the engineer who owns the API. It is often terrible for the agent. An agent does not want your internal resource model. It wants a small set of actions that match user intent. [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s writing on MCP production systems makes the same point from the platform side: tools should help agents complete real workflows, not mirror every endpoint one by one. For the broader MCP map, read the [complete MCP servers guide](/blog/complete-guide-mcp-servers) and the [MCP server shortlist](/blog/271-mcp-servers-top-5-that-matter). This post is the product-design layer underneath both. ## Endpoint Mirrors Create Tool Menu Tax Every tool definition [costs](/blog/ai-coding-tools-pricing-comparison) something. It costs tokens in the prompt. It costs attention when the model decides what to call. It costs reliability when the agent has to chain five low-level calls correctly. It costs observability when the final result is scattered across intermediate tool outputs. The failure mode is predictable: 1. The agent chooses the wrong low-level tool. 2. The tool returns too much raw data. 3. The agent loses the thread. 4. The agent retries with a slightly different call. 5. The context window fills with endpoint noise. This is the tool menu tax. You pay it on every task, even when the task is simple. ## Intent-Shaped Tools Work Better The better tool is shaped like the job. Bad: ```text searchSlack getThread summarizeThread createLinearIssue attachSlackLink postReply ``` Better: ```text create_issue_from_slack_thread ``` The better tool can still call Slack, summarize the thread, create the issue, attach the source link, and post a reply. The difference is that the agent sees one workflow-shaped capability instead of six infrastructure-shaped endpoints. The same pattern applies everywhere: ```text bad: listDeployments, getLogs, searchErrors, rollbackDeployment good: diagnose_failed_deploy bad: queryDatabase, getSchema, explainQuery, exportRows good: investigate_empty_dashboard bad: createBranch, editFile, runTests, openPullRequest good: implement_issue_with_pr ``` You do not remove power. You package it at the right level. ## The Tool Should Return a Receipt A production agent tool should not only return text. It should return a receipt. For example: ```json { "status": "created", "issueUrl": "https://linear.app/acme/issue/ENG-123", "sourceThread": "https://slack.com/archives/C123/p456", "summary": "Customer cannot export invoices after plan downgrade.", "actions": [ "read 14 Slack messages", "created Linear issue ENG-123", "attached source thread", "posted confirmation reply" ] } ``` That receipt gives the agent enough context to continue without dumping every Slack message into the model. It also gives the human something reviewable. This is the same principle behind [agent swarms needing receipts](/blog/agent-swarms-need-receipts). Orchestration without reviewable outputs becomes theater quickly. ## Thin Tools Still Have a Place This is not an argument against low-level tools entirely. Thin tools are useful when: - the domain is exploratory - the agent is debugging an unfamiliar system - the workflow is not stable yet - the user explicitly wants raw access - the tool is a universal primitive, like shell, grep, or SQL But once a workflow repeats, promote it. The first time the agent creates an issue from a Slack thread, a low-level chain is fine. The tenth time, that chain should become a tool, a CLI command, or a skill. That is how agent systems mature. ## How to Design the Tool Set Start with user jobs, not API resources. Ask: - What is the user actually trying to accomplish? - What evidence should the tool collect? - What side effects should be atomic? - What should be returned as a receipt? - What should require human confirmation? - What should never be exposed to the agent? Then design the tool around that. The right tool set is usually smaller than the API. A calendar API might expose 80 operations. The agent might need five: - `find_meeting_time` - `schedule_meeting_from_thread` - `summarize_day` - `move_meeting_with_notice` - `prepare_meeting_brief` That is enough to do real work. ## The Bottom Line Agents do not need every endpoint. They need the right affordances. If your [MCP](/blog/what-is-mcp) server exposes your whole REST API, you probably built an integration, not an agent tool. The next step is product design: compress repeated workflows into intent-shaped tools, return receipts, and keep the raw endpoint surface available only when it actually helps. One good tool beats ten endpoints because the agent is not paid to navigate your API. It is there to finish the job. ## Sources - Anthropic: [Building agents that reach production systems with MCP](https://claude.com/blog/building-agents-that-reach-production-systems-with-mcp) - Anthropic Engineering: [Code execution with MCP](https://www.anthropic.com/engineering) - DevDigest: [CLIs Over MCPs](/blog/clis-over-mcps) - DevDigest: [MCP vs Function Calling](/blog/mcp-vs-function-calling)

Open Design Shows the Next Agent Wrapper

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The most interesting Hacker News thread today is not really about design. It is about what happens when [coding agents](/blog/what-is-an-ai-coding-agent-2026) stop being a terminal box and start becoming product engines. [Open Design](https://github.com/nexu-io/open-design) hit the front page with a big promise: use your coding agent as a design engine. The repo describes itself as a local-first, open-source alternative to Claude Design. It auto-detects a long list of coding-agent CLIs on your machine, including Claude Code, Codex, Cursor Agent, Gemini CLI, OpenCode, Qwen, Copilot CLI, Hermes, and Kimi. Then it wraps those agents with skills, design systems, prompt templates, a local daemon, sandboxed previews, exports, and persistence. That is a lot of machinery. The obvious take is "AI can design now." That is too shallow. The better take is this: agent products are moving from chat interfaces to artifact wrappers. ## The wrapper is becoming the product Most coding agents already have the raw abilities Open Design wants to use. For the design side of the same problem, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) with [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they show how agent-generated interfaces fail and how to give coding agents better visual constraints. They can read files. They can write files. They can run shell commands. They can open docs. They can generate HTML. They can revise based on feedback. In a strong repo, they can even follow local design rules if you give them a good `[DESIGN.md](/blog/design-md-for-ai-agents)`. Open Design does not win by making the model smarter. It wins, if it wins, by narrowing the loop: - choose a surface - choose a design system - ask clarifying questions before generating - stream a plan - write a real project folder - render a sandboxed preview - export the artifact - keep the project state around for tomorrow That is not a chatbot. That is a product wrapper around a coding agent. This is the pattern worth paying attention to. The frontier models are becoming broadly capable enough that the valuable layer is less "can the model make a thing?" and more "can the product force the model into the right workflow for this kind of thing?" ## Design is a good stress test Frontend and design work expose agent weakness faster than backend work. Backend code has sharper receipts. A test passes or fails. A typecheck catches a broken contract. A database migration applies or it does not. Design has softer receipts. The page can render and still look wrong. The hierarchy can technically fit and still feel cheap. The colors can come from the system and still clash. A screenshot can be "correct" while the product feels incoherent. That is why Open Design is interesting as a stress test. It tries to add structure where agents usually freestyle: - built-in skills - brand-grade design systems - visual direction choices - device frames - critique passes - sandboxed previews - export formats Some of that may be too much. The Hacker News skepticism was direct: the README reads like a sales deck, the workflow can be token-heavy, and the output risks becoming more generic visual noise. That criticism is fair. But the presence of criticism does not make the category unimportant. It points to the real bar. Agent design tools will not be judged by whether they can make a slick first draft. They will be judged by whether they can preserve taste across revisions. ## The opposing view is right about generic output The strongest pushback in the thread was that infinitely generated design work becomes background noise. That is already happening. AI can produce endless pitch decks, landing pages, social cards, dashboards, mockups, diagrams, and brand systems. Most of them look like they came from the same expensive template pack. They are polished, empty, and hard to trust. This is the trap for artifact-first agents. If the wrapper only helps the model generate more output, it accelerates slop. If the wrapper helps the model preserve constraints, compare alternatives, revise against a critique, and keep evidence attached to decisions, it becomes useful. That distinction matters more than the model provider. A design agent does not need to be "creative" in the vague sense. It needs to be constrained in the useful sense: - use this brand system - respect this layout density - preserve this component hierarchy - keep this product promise visible - avoid this banned language - show the next section above the fold - run the screenshot check - revise only the broken part That is not magic. It is workflow. ## The CLI aggregator angle is underrated One underrated part of Open Design is that it does not assume one agent. The repo positions the local daemon as the privileged process and treats the agent CLI as swappable. That is a subtle but important product bet. Developers already live in a multi-agent world. [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Codex, Cursor, Gemini, Kimi, Qwen, OpenCode, Copilot, and local models all have different strengths, prices, limits, and ergonomics. A serious artifact tool cannot assume the user wants one model forever. The wrapper pattern gives you a cleaner abstraction: - the product owns the workflow - the local daemon owns execution - the agent owns generation and revision - the design system owns constraints - the preview owns feedback That is more durable than betting the whole product on one provider's chat surface. It also explains why these wrappers keep appearing. The agent layer is powerful but unstable. The product layer can stabilize the task. ## What I would steal for developer tools Open Design is framed around design, but the pattern applies to developer workflows more broadly. Imagine the same artifact-first wrapper for: - API migration plans - code review reports - incident postmortems - database schema changes - docs refreshes - release notes - synthetic monitoring checks - agent run replays The user should not have to prompt from scratch every time. The product should know the artifact shape, the review loop, the export target, and the evidence requirements. For a database migration, that means schema diff, rollback plan, dry-run output, generated SQL, and test evidence. For a code review, it means changed files, behavioral risk, line comments, missed tests, and a confidence level. For a docs refresh, it means source docs, changed claims, screenshots, and a stale-link check. That is the lesson from Open Design: the future is not one giant agent prompt. It is many narrow artifact factories. ## The practical test If you are evaluating tools like this, ignore the launch copy and ask five questions: 1. Does it produce a real artifact I can inspect outside the chat? 2. Does it preserve state between sessions? 3. Does it force the agent to ask for missing constraints before generating? 4. Does it provide a preview or test surface that catches obvious failures? 5. Does it make revision cheaper than starting over? If the answer is no, it is probably just a fancy prompt box. If the answer is yes, it may be the shape of the next wave of developer tools. Open Design might not be the final version of this category. The HN thread is right that the current surface can feel heavy, and the category is already crowded with demos that overpromise. But the architecture signal is real. The next serious agent products will not ask users to watch a model think. They will wrap the model in a workflow that produces something inspectable, revisable, and exportable. That is the shift.

OpenAI Codex, Managed Agents, and AWS: What Developers Should Watch

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

OpenAI's developer story is no longer just "call a model from your app." The current direction is broader: [Codex](/blog/openai-codex-guide) for software work, the [Responses API](/blog/openai-responses-api-migration) for custom agents, and managed agent infrastructure for teams that do not want to assemble the whole harness themselves. The companion read is [Codex as a general-purpose AI agent](/blog/codex-general-purpose-ai-agent), which covers the non-code workflow angle. That matters for search intent because developers are no longer asking one question. They are asking a stack of related questions: - What is Codex now? - Is Codex just for code, or for wider knowledge work? - What are Managed Agents? - Should I build on the Responses API, Codex, or AWS Bedrock? - How does this compare to Claude Code, [GitHub Copilot](/blog/github-copilot-coding-agent-cli-2026), and Cursor? This is the map. ## OpenAI Agent Platform Map The nearby posts split the [OpenAI](/blog/openai-vs-anthropic-2026) story by layer: | Layer | Best next read | |-------|----------------| | Codex product basics | [OpenAI Codex guide](/blog/openai-codex-guide) | | Recent Codex product direction | [Codex changelog April 2026](/blog/codex-changelog-april-2026) | | Long-running agent control | [Codex `/goal` vs Claude Managed Outcomes](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences) | | OpenAI versus Anthropic platform choice | [Anthropic vs OpenAI developer experience](/blog/anthropic-vs-openai-developer-experience) | | Agent implementation layer | [OpenAI Agents SDK TypeScript](/blog/openai-agents-sdk-typescript) and [Responses API migration](/blog/openai-responses-api-migration) | | Tool and budget choice | [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) | Primary sources to verify while this category moves: OpenAI's [Codex changelog](https://developers.openai.com/codex/changelog), [Codex for almost everything](https://openai.com/index/codex-for-almost-everything/), [new tools for building agents](https://openai.com/index/new-tools-for-building-agents/), and [OpenAI on AWS](https://openai.com/index/openai-on-aws/). ## Codex Is Becoming an Agent Workspace OpenAI's April update, [Codex for almost everything](https://openai.com/index/codex-for-almost-everything/), is the clearest signal. Codex is being positioned as a workspace for running agents across the software development lifecycle, not just a terminal coding tool. For the OpenAI side of the agent stack, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) with [Codex vs Claude Code in April 2026: Which Agent for Which Job](/blog/codex-vs-claude-code-april-2026); that gives the product and workflow context behind this update. The new surface includes [computer use](/blog/claude-computer-use), an in-app browser, image generation, plugins, memory, multiple terminals, PR review workflows, SSH devboxes, automations, and scheduled follow-up work. The important part is not any single feature. The important part is the product shape. Codex is turning into an agent operating surface. For developers, that means the competitive frame changes. The old comparison was: > Codex vs [Claude Code vs Cursor](/blog/cursor-vs-claude-code-2026) for writing code. The new comparison is: > Which tool can safely coordinate agents across code, browser QA, review comments, docs, design, CI, and repeated operational tasks? That is a bigger market. ## AWS Makes Codex an Enterprise Procurement Story OpenAI's [AWS partnership announcement](https://openai.com/index/openai-on-aws/) adds the enterprise side. OpenAI models, Codex, and Amazon Bedrock Managed Agents are coming to AWS in limited preview. For developers inside companies, this changes the adoption path. A lot of teams cannot simply swipe a card for a new AI coding tool and point it at production code. They need procurement, security review, data controls, billing alignment, compliance, and support. Codex on Bedrock gives those teams a path where the agent can be powered through the infrastructure they already use. OpenAI says customers can configure Codex to use Bedrock as the provider, starting with Codex CLI, the Codex desktop app, and the VS Code extension. That puts Codex closer to the category GitHub has been aiming at with Copilot coding agent: asynchronous work inside enterprise controls. It also makes the [Codex vs Claude Code](/blog/codex-vs-claude-code-april-2026) comparison less about model taste and more about operating model. ## Managed Agents Are the Real Trend The phrase "Managed Agents" is worth watching. It means teams are moving past the basic model-call layer. An unmanaged agent stack usually means you own: - The prompt loop - Tool execution - State and memory - Sandboxing - Secrets - Observability - Eval traces - Deployment - Retry behavior - Governance That is a lot of infrastructure before the agent does anything useful. Managed Agents are an attempt to package more of that operational layer. Amazon Bedrock Managed Agents, powered by OpenAI, is pitched as a way to maintain context, execute multi-step workflows, use tools, and operate inside AWS security and compliance controls. For app builders, this means the question becomes less "can I build an agent?" and more "which layer should I own?" If you need full product control, build on the [Responses API](https://openai.com/index/new-tools-for-building-agents/). If you need a coding agent for repo work, use [Codex](/blog/openai-codex-guide). If you need governed enterprise deployment inside AWS, watch Managed Agents. ## Responses API Is Still the Build Layer The Responses API is the OpenAI primitive for custom agents. It combines model calls, built-in tools, streaming, structured output patterns, and hosted state into a more agent-friendly API. If you are migrating older OpenAI agent code, the [Responses API migration guide](/blog/openai-responses-api-migration) is the implementation-level companion to this strategy post. OpenAI has been clear that the Responses API is the preferred direction for new agent integrations. The older Assistants API is being folded toward this model. The practical decision tree: | Need | Best starting point | |------|---------------------| | Codebase edits, tests, PRs | Codex | | Custom agent inside your app | Responses API | | Enterprise agent deployment on AWS | Bedrock Managed Agents | | Low-level framework control | Agents SDK or your own loop | Do not force Codex to be your product runtime. Do not rebuild Codex if the job is mostly repo work. Pick the layer that matches the ownership boundary. ## What This Means for Developers The highest leverage move is to separate three workflows: 1. **Build agents** with the Responses API when the agent is part of your product. 2. **Run coding agents** with Codex when the task is repo-centered. 3. **Deploy managed agents** when governance, observability, security, and procurement matter more than framework flexibility. This is the same pattern we are seeing across the market. [Claude Code](/blog/what-is-claude-code-complete-guide-2026) owns the local terminal agent workflow. [GitHub Copilot](/tools/github-copilot) owns the GitHub-native workflow. Codex is trying to own the broader agent workspace. The trend is not "AI writes code now." That was 2024. The 2026 trend is managed delegation: agents that can work across tools, remember context, run in controlled environments, and hand back reviewable artifacts. ## SEO Keywords to Watch If you are tracking this market, these are the queries worth owning: - OpenAI Codex AWS - Codex Managed Agents - Bedrock Managed Agents OpenAI - Codex vs Claude Code - Codex desktop app - Responses API agents - OpenAI Agents SDK vs Responses API - managed AI agents for developers The content opportunity is still early because the terminology is moving faster than the docs. Developers will search for "managed agents" before they fully know whether they mean OpenAI, AWS, Claude, GitHub, or a homegrown orchestration stack. That is exactly when practical explainers win.

Refusal Directions Are a Systems Problem

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

[Refusal in Language Models Is Mediated by a Single Direction](https://arxiv.org/abs/2406.11717) is back on Hacker News, and the discussion is exactly what you would expect: interesting mechanism, jailbreak implications, and debate over whether the result is already stale. The paper's core claim is simple and uncomfortable. Across a set of open-source chat models, the authors found a one-dimensional direction in the residual stream that strongly mediates refusal behavior. Remove it, and harmful requests are less likely to be refused. Add it, and harmless requests can become refusals. That does not mean every modern model can be made unsafe with one magic vector. One Hacker News commenter pointed to newer research arguing that models can spread refusal behavior across more directions, which may make this specific intervention less direct. But the broader lesson still matters for builders. If model safety depends on one brittle behavior layer, you do not have a safety system. You have a feature. ## The refusal layer is not the safety system Refusal behavior is visible, so people treat it as the safety mechanism. The model says no. The product looks safer. But product safety is not the same thing as refusal text. A serious system has to account for: - what the user asked - what tools are available - what data is accessible - what actions are allowed - what outputs are reviewed - what logs are retained - what policies apply outside the model That is especially true for agents. A chat model that answers a question badly is one risk profile. An agent with shell access, browser access, API keys, database permissions, or deployment rights is another. For agent products, safety cannot live only inside the model's final response. It has to live in the harness around the model. That connects to the same architecture lesson behind [agent reliability](/blog/the-agent-reliability-cliff): the model is one component in a larger control loop. ## Why mechanism research matters to product teams Mechanistic interpretability can feel far from everyday app development. This paper is a good example of why it is not. If refusal behavior can be localized, redirected, suppressed, or distributed, then product teams should stop thinking of safety as a single prompt or single fine-tuning property. They should think in layers: 1. Policy: what the system is allowed to do. 2. Interface: what requests users can make. 3. Retrieval: what context the model can see. 4. Tools: what actions the model can take. 5. Runtime: what the harness permits. 6. Output: what gets filtered, reviewed, or logged. 7. Evaluation: what red-team tests keep running. The refusal layer is one layer. It is not the whole stack. This is the same reason [prompt injection](/blog/prompt-injection-open-source) remains hard. You cannot solve it by asking the model to be careful. You need boundaries around data, tools, and authority. ## The opposing view The fair opposing view is that the paper is old by AI standards. It was first submitted in June 2024 and revised in October 2024. The HN thread included a comment saying newer models are trained to resist simple "abliteration" by spreading refusal encodings across the network. That is a serious caveat. Builders should not read this paper as a current universal exploit recipe. They should read it as evidence that model behavior can be more mechanically brittle than product teams assume. The exact technique may age. The system lesson ages slower. If one generation concentrates refusal behavior in a direction and another generation distributes it, the product conclusion is still the same: do not depend on the model's internal refusal behavior as your only control. ## Refusal quality also matters There is another practical problem: refusals are often badly calibrated. Developers have seen models refuse harmless requests, over-explain policy, or block useful debugging context. They have also seen models comply in places they should slow down. That means the safety layer has two jobs: - prevent dangerous misuse - avoid uselessly blocking legitimate work A refusal-only product experience tends to handle both poorly. Better systems separate risk classification from tool authority. For example, a model can discuss a high-level concept while the harness blocks execution of risky commands. Or an agent can draft a migration plan while requiring approval before touching production. That is a stronger pattern than hoping the model's text refusal is perfectly calibrated. ## What AI app builders should do If you are building with LLMs or agents, the practical takeaway is not to panic. It is to move safety out of vibes and into architecture. Start with tool boundaries: - do not expose unnecessary tools - scope credentials narrowly - wrap privileged commands - require approval for irreversible actions - keep secrets out of model context - log tool calls and decisions Then add task-specific evaluation: - benign requests that should not be refused - risky requests that should be blocked - ambiguous requests that should ask clarifying questions - tool-use attempts that should require approval - prompt-injection attempts against retrieved context Finally, make the product degrade gracefully. When the model refuses, the user should know what boundary was hit and what safe alternative exists. When the harness blocks an action, the system should explain whether it needs approval, a different permission, or a narrower request. That is more useful than a generic "I cannot help with that." ## Where this fits in the agent stack The trend across developer AI is clear. Models are getting more capable, but the surrounding system is becoming more important, not less. [Flue's harness framing](/blog/flue-agent-harness-layer), [jcode's session-runtime focus](/blog/jcode-coding-agent-harness), and safety research like this all point to the same conclusion: The model is not the product boundary. The product boundary is the system that wraps the model. For [AI agents](/blog/ai-agents-explained), that means permissions, tools, traces, approvals, evaluations, and deployment constraints. For chat products, it means retrieval boundaries, output review, data minimization, and policy-aware UX. Refusal is visible. Boundaries are what make it reliable. ## My take The refusal-direction paper is not interesting because it gives builders a trick. It is interesting because it shows why thin safety layers are a bad bet. Modern AI products should assume model behavior will be probed, shifted, optimized around, and occasionally misunderstood. The answer is not to abandon model-level safety. The answer is to stop treating it as the only layer. Good AI systems need refusals, but they also need constrained tools, narrow credentials, reviewable traces, and task-specific evaluations. That is the real takeaway for developers. Safety is not a sentence the model says. It is the system the model runs inside.

Skills Are How Agents Learn the Job

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

A general [coding agent](/blog/what-is-an-ai-coding-agent-2026) is smart. A skilled coding agent knows the job. That distinction matters. Most agent failures are not caused by the model being unable to write code. They are caused by missing local knowledge: - how this repo deploys - what tests actually matter - which files are generated - how design tokens work - what language the brand never uses - how to debug the recurring production issue - what "done" means for this team You can repeat that context in every prompt. Or you can package it as a skill. [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s framing of skills is useful: a skill is not just a prompt. It is a folder of instructions, scripts, examples, and resources that the agent can load when a task calls for it. That is closer to a runbook than a chat trick. For the broader control-stack argument, read [why skills beat prompts](/blog/why-skills-beat-prompts-for-coding-agents-2026) and the [context engineering guide](/blog/context-engineering-guide). This post is the operating model. ## Prompts Teach the Task. Skills Teach the Job. A prompt is usually about the immediate request: ```text Add a pricing page with three tiers. ``` A skill teaches the recurring method: ```text When adding a public marketing page: - use the Gumroad card pattern - no gradients - no emojis - no em dashes - update the navigation only if the route is strategic - add internal links to related comparison posts - run the route locally and check mobile layout ``` The prompt changes every day. The skill compounds. That is the core value. Skills let the agent carry team knowledge across tasks without turning every user prompt into a 4,000-token policy document. ## The Best Skills Are Boring The most useful skills are not magical. They are boring workflows that happen often: - add a blog post - fix CI - debug a deploy - review a PR - add a database table - generate a hero image - test a checkout flow - publish release notes - triage a production incident These tasks have a right shape. They have known pitfalls. They have commands that usually work and commands that usually waste time. That is exactly what belongs in a skill. ## What Goes Inside a Skill A strong skill usually has five pieces. **Trigger.** When should the agent use it? **Workflow.** What sequence of steps works? **Constraints.** What should the agent avoid? **References.** Which files, docs, or examples matter? **Scripts.** Which helper commands reduce repeated work? For example, a deployment-debugging skill might include: ```text Trigger: user reports deploy failure, Coolify issue, 502, failed build, or missing env var. Workflow: 1. Inspect latest build logs. 2. Check environment variables. 3. Reproduce locally only if needed. 4. Search Obsidian runbooks before guessing. 5. Verify health route after fix. Pitfalls: - Do not assume Vercel. - Do not restart production before reading logs. - Do not expose secrets in chat. ``` That is not a fancy prompt. It is operational memory. ## Skills Reduce Context Waste Skills also solve a context problem. Without skills, durable instructions live in one of three bad places: - the user's memory - the model's prompt - stale documentation no agent reads With skills, the agent can discover the skill list and load only the relevant skill body when needed. The current task gets the right method without dragging every possible workflow into context. This is the same logic behind [progressive disclosure in Claude Code](/blog/progressive-disclosure-claude-code): keep the full library available, but only load what matters for the current job. ## Skills Beat Specialized Agents More Often Than You Think Teams love creating specialized agents: - frontend agent - backend agent - security agent - docs agent - deploy agent Sometimes that is right. But a lot of the time, what you actually need is one strong general agent with better skills. The difference: - A specialized agent changes the persona and permissions. - A skill changes the method and knowledge. If the task needs different tool access, use a subagent. If the task needs a known workflow, use a skill. Mixing those up creates agent sprawl. ## Skills Should Improve The strongest skills are living artifacts. When the agent makes a recurring mistake, update the skill. When a command changes, update the skill. When a new pitfall appears, update the skill. When a workflow gets simpler, remove old steps. This is how teams teach agents the same way they teach people: by turning repeated corrections into reusable training. The habit matters more than the file format. ## The Bottom Line Skills are how agents learn the job. They turn scattered corrections into durable method. They keep prompts shorter. They make repeated work more reliable. They let a general agent behave like it has worked in the repo before. The future of coding agents is not just better models. It is better training material around the models: skills, runbooks, examples, scripts, and receipts. That is what makes the agent useful on day ten, not just impressive on day one. ## Sources - Anthropic: [Building agents with Skills](https://claude.com/blog/building-agents-with-skills-equipping-agents-for-specialized-work) - Anthropic: [How Anthropic teams use Claude Code](https://claude.com/blog/how-anthropic-teams-use-claude-code) - DevDigest: [Why Skills Beat Prompts for Coding Agents](/blog/why-skills-beat-prompts-for-coding-agents-2026) - DevDigest: [Self-Improving Skills](/blog/self-improving-skills-claude-code)

Skills Are the New Agent Operating System

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

The most interesting AI developer trend today is not another benchmark. It is the return of process. On May 2, 2026, GitHub trending had multiple agent-shaped projects near the top. The clearest signal was [`obra/superpowers`](https://github.com/obra/superpowers), an agentic skills framework and software development methodology, sitting on the trending page with a huge public star count and more than a thousand stars added that day. Nearby, [`browserbase/skills`](https://github.com/browserbase/skills) framed a similar idea around web browsing for Claude Agent SDK. That is a different category from "AI writes code now." These projects are not trying to make the model smarter. They are trying to make the model behave like it works on a team. The take: skills are becoming the operating system for [coding agents](/blog/what-is-an-ai-coding-agent-2026). Not because markdown files are magic. They are not. Because every serious agent workflow eventually runs into the same wall: prompts do not preserve engineering discipline by themselves. ## The old failure mode was prompt drift Most teams start with one giant instruction file. For the larger agent workflow map, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) and [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they give the architecture and implementation context this piece assumes. It says how to run tests. It says how to name branches. It says not to touch billing logic without review. It says to use the design system. It says to check current docs before answering framework questions. It says twenty other things that are all important. Then the agent ignores half of it. Not because the model is malicious. Because the context is too broad, the task feels urgent, and the instruction that mattered most was buried under a pile of other rules. This is prompt drift. The workflow starts disciplined. Then the prompt grows. Then the model treats the whole thing like ambient style guidance instead of an execution contract. Eventually, a human writes "please actually run the tests" for the third time in the same afternoon. Skills are an answer to that problem. Instead of carrying every rule all the time, the agent gets small, named operating procedures that load when relevant: - how to research a library - how to review a pull request - how to make a Gumroad-style blog image - how to run browser QA - how to decompose a task across agents - how to save session context - how to debug a known deployment target That is a better primitive than one huge prompt because it matches how engineering teams already work. You do not keep the whole company handbook in your head. You pull the runbook for the situation in front of you. ## Why Superpowers hit a nerve The Hacker News thread around Superpowers is useful because it shows both sides of the reaction. One developer described a structured workflow: brainstorm first, write a design plan, review it, write an implementation plan, use worktrees and [subagents](/blog/claude-code-sub-agents), then require implementation, spec review, and code review before merge. That is a real methodology. It is slow compared with a one-shot prompt, but it maps cleanly to the parts of software work that keep code from rotting. The pushback was also fair. Another commenter argued that much of this is already available in modern coding tools: worktrees, memory files, plan review, research subagents, IDE integration, and documentation fetching. The skeptical version is: why install another framework when the base tools are catching up every week? That criticism lands. If a skill framework only wraps features your agent already has, it is ceremony. But the stronger argument for skills is not feature access. It is repeatability. The built-in tool can create a plan. A skill can define what your team considers a good plan. The built-in tool can spawn a subagent. A skill can define when a subagent should be used, what evidence it must return, and what files it is allowed to touch. The built-in tool can run a test. A skill can define which tests count for this project, when a screenshot is required, and what unresolved risk has to be reported. That is the difference between a capability and an operating procedure. ## Skills turn taste into infrastructure Senior engineers carry a lot of tacit rules. They know when a refactor is too broad. They know when a UI change needs browser verification. They know when a migration needs a rollback path. They know when a library answer needs current docs instead of memory. They know when a task should be split and when splitting it will create coordination overhead. Agents do not naturally have that local judgment. A skill is a way to package some of it. For example, this site has rules that matter: - no emojis - no gradients - no em dashes - Gumroad-style cards and pill buttons - pink only on white or black - blog posts need frontmatter and a hero image - public content cannot include private business details Those are not universal programming laws. They are local taste and local safety rules. They belong in project instructions and project skills, not in a generic model prompt. This is why skills are more interesting than the current hype suggests. The market tends to frame them as "downloadable powers." The better frame is "portable team process." ## The security story is not optional There is a hard caveat: agent skills are also a new supply chain surface. A recent paper, [Towards Secure Agent Skills](https://www.emergentmind.com/papers/2604.02837), argues that skills create structural risk because they mix natural-language instructions, local files, scripts, and persistent trust. The authors call out issues like weak data-instruction boundaries, single-approval trust, missing marketplace review, prompt injection, credential leakage, and post-install modification. That should change how developers install skills. Treat a third-party skill less like a blog post and more like a package with a shell script. Before installing one, ask: - Does it run code? - Does it fetch remote dependencies? - Does it ask the agent to read secrets or config? - Does it change memory or persistent settings? - Is the source pinned to a commit? - Can I inspect every file quickly? - Would I run this in a repo with production credentials? If the answer is fuzzy, do not install it globally. Use project-local skills for project-local behavior. Vendor the skill when it matters. Keep execution helpers small. Prefer read-only workflows unless a skill truly needs write access. The uncomfortable truth is that the skill ecosystem currently feels like early npm, but with natural-language instructions sitting beside executable code. That is powerful. It is also messy. ## The practical stack For a development team, the useful stack is simple: ```text AGENTS.md or CLAUDE.md Project identity, rules, architecture, commands, safety boundaries. Skills Reusable procedures for recurring work. Tools Real observation and execution: tests, browser, docs, database, logs. Receipts Diffs, command output, screenshots, source links, open risks. ``` That stack keeps the agent grounded. The project file answers "where am I?" The skill answers "how do we do this kind of work here?" The tool answers "what is actually true?" The receipt answers "how can a human verify it?" Leave out any layer and the workflow degrades. A project file without skills becomes a giant prompt. Skills without tools become ritual. Tools without receipts become invisible work. Receipts without project rules become generic status reports. ## What to automate first Do not start by installing fifty public skills. Start with the repetitive work you already correct agents on. Good first skills: - code review checklist for your repo - frontend visual QA flow - deployment debugging runbook - documentation lookup policy - content publishing checklist - database migration safety checklist - PR closeout checklist Each skill should be small enough to audit and specific enough to trigger only when useful. Bad first skills: - "be a better engineer" - "write cleaner code" - "understand our company" - "build anything end to end" Those are aspirations, not procedures. A good skill has a concrete activation moment. When the user asks for a PR review, load the review skill. When a file imports Stripe, load the payment safety skill. When the work touches `app/page.tsx`, load the design-system skill. That is how skills stay useful instead of becoming a second prompt landfill. ## The recommendation Skills are worth taking seriously, but not as a marketplace shopping spree. Use public frameworks like Superpowers to study the workflow shape. Borrow the parts that improve your agent behavior. Then write your own smaller project-local skills for the work your team repeats. The best skill system is not the one with the most commands. It is the one that makes the agent stop skipping the boring steps that protect the codebase. That means plans before risky edits. Tests before claims. Browser checks before UI summaries. Source links before research conclusions. Diff boundaries before merge. The agent future is not just more autonomy. It is more inspectable process. And right now, skills are the cleanest place to put that process.

VS Code Copilot Co-Author Attribution: The Real Problem Is Workflow Consent

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

VS Code 1.118 shipped a small source-control default with a much bigger trust problem. The official [VS Code 1.118 release notes](https://code.visualstudio.com/updates/v1_118) say Git AI co-authoring is now enabled by default for chat and agent workflows. When Copilot changes files, VS Code can automatically add Copilot as a co-author on the commit. The source-control docs explain the underlying setting, [`git.addAICoAuthor`](https://code.visualstudio.com/docs/sourcecontrol/staging-commits), and the available modes: `off`, `chatAndAgent`, and `all`. That sounds tidy. It is just a `Co-authored-by:` trailer. But the reaction on [Hacker News](https://news.ycombinator.com/item?id=47570269), Reddit, and GitHub-adjacent forums is not really about one line of commit metadata. Developers are arguing about who gets to write into the permanent record of a repo, whether AI usage should be disclosed, and whether a tool default should silently become team policy. This is a good argument to have because every coding agent is about to run into the same boundary. For the broader Copilot platform shift, read [GitHub Copilot Coding Agent and CLI](/blog/github-copilot-coding-agent-cli-2026). For the workflow-trust layer behind this story, pair it with [The Agent Reliability Cliff](/blog/the-agent-reliability-cliff) and [What Hacker News Gets Right About AI Coding Agents](/blog/what-hacker-news-gets-right-about-ai-coding-agents-2026). ## What Actually Changed VS Code introduced the setting earlier with `off` as the default. In 1.118, the release notes say the default is enabled for chat and agent workflows. The behavior applies when Copilot makes changes to files and the commit is created through VS Code's built-in Git flow. The docs matter because the scope is narrower than some angry summaries imply: - `off` adds no AI co-author trailer. - `chatAndAgent` adds the trailer for Copilot Chat or agent-mode generated code. - `all` extends the behavior to inline completions. - Commits made outside VS Code, such as from the command line, do not get this trailer from VS Code. The practical fix is simple: ```json { "git.addAICoAuthor": "off" } ``` That solves the local annoyance. It does not solve the policy question. ## Why Developers Are Mad Git history is not decorative UI. Commit metadata feeds code review, blame, release notes, compliance systems, security audits, dashboards, and future debugging. Once a default tool setting writes into that layer, it stops being a personal preference and starts acting like workflow policy. That is why this landed badly. Developers are not only objecting to AI attribution. Some people actively want AI-generated work labeled. The deeper objection is that the default changed in a place where the user expected authorship and commit hygiene to remain under their control. There are three separate concerns getting mashed together: 1. **Authorship:** Should an AI tool be listed as a co-author at all? 2. **Disclosure:** Should commits disclose when agent-generated code was involved? 3. **Consent:** Who gets to decide the default for that disclosure? The third one is the real issue. If a team requires AI attribution, that should be explicit. If a team bans AI attribution in commit trailers and tracks usage elsewhere, that should also be explicit. A surprise editor default is the worst possible place to make the decision. ## The Best Case for AI Attribution There is a real argument for labeling agent-written commits. AI-generated changes often need different review pressure. A reviewer might want to inspect edge cases more closely, ask for stronger tests, or look for familiar failure modes: broad refactors, invented APIs, missing migrations, fake confidence, or accidental changes outside the requested scope. Attribution can also help teams measure what is happening: - Which commits were mostly agent-generated? - Which tools produce reviewable diffs? - Which workflows save time? - Which agents create cleanup work? - Which models are safest for high-risk files? That is useful operational data. In the same way [AI coding tools pricing](/blog/ai-coding-tools-pricing-q2-2026) is shifting from sticker price to usage accounting, agent productivity will shift from vibes to accepted-change telemetry. There is also precedent for structured trailers. Open-source projects already use trailers like `Reviewed-by`, `Signed-off-by`, `Co-authored-by`, and `Reported-by`. The idea that Git metadata can carry workflow signals is not new. So the pro-attribution case is not silly. The weak version is "the AI deserves credit." The strong version is "reviewers and teams need machine-readable provenance signals." That distinction matters. ## The Best Case Against It The counterargument is also strong: tools are not authors. Developers already use compilers, IDEs, formatters, linters, autocomplete, generators, snippets, Stack Overflow, docs, and internal templates. We do not list all of them as co-authors. The human who chooses, reviews, commits, and ships the change owns the outcome. That ownership point is not philosophical fluff. It is the accountability model software teams actually use. If a production bug ships, the answer cannot be "Copilot co-authored it." The responsible party is the human and organization that accepted the change. A trailer that makes accountability feel shared with a vendor-owned tool can muddy the signal instead of clarifying it. The other problem is false precision. A commit may include: - one AI-written helper function - one human refactor - one generated test - one manual bug fix - one agent-suggested commit message Flattening all of that into a co-author trailer can imply more certainty than the tool really has. If multiple agents touched the code, the tool that happened to run the commit command may get the attribution even if another model did the meaningful work. That is not provenance. That is accidental bookkeeping. ## The Better Pattern: Policy Before Metadata The right answer is not "always add AI co-author trailers" or "never disclose AI use." The right answer is: teams should choose the attribution layer deliberately. For small personal repos, a VS Code setting is probably enough. If you like the signal, leave it on. If you hate it, turn it off. For teams, decide this in the repo: ```md ## AI attribution policy - Humans remain accountable for every commit they push. - AI-generated code must be reviewed to the same standard as human code. - We do not use `Co-authored-by` trailers for AI tools. - Significant agent-generated work should be disclosed in the PR description under "AI assistance". - Agent sessions that modify security, auth, billing, or data migrations require extra review. ``` Or choose the opposite: ```md ## AI attribution policy - Commits with substantial agent-generated code should include an AI provenance trailer. - The trailer should name the tool only when it materially generated the committed diff. - The PR description must still name the human owner and summarize verification. - The human committer remains responsible for the final change. ``` Either policy is better than drift. Mixed histories are the bad outcome: one developer commits through VS Code with the trailer, another uses the CLI without it, another disables the setting, another uses Claude Code, another uses Codex, and now the repo has a provenance signal nobody can interpret. ## What I Would Do I would turn the VS Code default off for team repos unless the team has explicitly decided to use commit trailers as the AI provenance layer. Then I would add AI disclosure to the pull request template instead. PRs are a better place for this signal because they can carry context: - which tool was used - what it was asked to do - which files it touched - what the human changed afterward - what tests were run - where the reviewer should be skeptical A commit trailer can say an AI touched the work. A PR section can explain how. For agent-heavy teams, go further. Store session logs, prompts, tool traces, and model metadata in the agent system itself. Link the useful audit artifact from the PR. Do not try to stuff the whole provenance story into one Git footer. That is also the lesson from [agent reliability work](/blog/the-agent-reliability-cliff): serious agent workflows need verification artifacts, not just generated output. ## The Bigger Product Lesson AI coding tools are moving from helpers to actors. That means defaults matter more. A default that edits code is one thing. A default that edits workflow metadata is another. A default that writes into PR descriptions, commit messages, authorship fields, issue comments, or release notes is operating in the social layer of software development. That layer is sensitive because it encodes trust. This is where the Hacker News skepticism is useful. Developers are not rejecting attribution because they want to hide AI use. Many are rejecting vendor-controlled attribution because they want the human workflow boundary to stay clear. Copilot, Claude Code, Codex, Cursor, and every other agent platform should treat this as a design rule: > AI tools can suggest workflow metadata, but they should not silently claim workflow identity. Make it visible. Make it configurable. Let teams set policy. Keep the human accountable. That is how AI attribution becomes useful instead of becoming another reason developers distrust the tools. ## FAQ ### How do I turn off Copilot co-author attribution in VS Code? Add this to your VS Code settings: ```json { "git.addAICoAuthor": "off" } ``` The official VS Code source-control docs list the supported values as `off`, `chatAndAgent`, and `all`. ### Does this affect command-line Git commits? VS Code's docs say the trailer is added only when committing from inside VS Code. Commits made with external Git tools or the command line do not include the trailer from this VS Code feature. ### Should AI-generated code be disclosed? Often yes, but disclosure should be policy-driven. For most teams, a PR template or agent-session log is clearer than a blanket co-author trailer because it explains what the tool did and what the human verified. ### Is Copilot legally an author? This post is not legal advice. In practical engineering terms, the human and organization accepting the change remain accountable for the code. Teams with compliance requirements should decide the policy with legal and security stakeholders rather than inheriting an editor default. ## Sources - [VS Code 1.118 release notes](https://code.visualstudio.com/updates/v1_118) - [VS Code source-control docs: staging and committing changes](https://code.visualstudio.com/docs/sourcecontrol/staging-commits) - [VS Code pull request for enabling AI co-author by default](https://github.com/microsoft/vscode/pull/310226) - [Hacker News discussion: Copilot edited an ad into my PR](https://news.ycombinator.com/item?id=47570269)

Warp Open Sourced the Terminal. The Real Story Is Agent Operations

Developers Digest — Sat, 02 May 2026 00:00:00 GMT

Warp open sourced its client this week, and the obvious headline is already everywhere: the AI terminal is now public on GitHub. That is true, but it is not the interesting part. The interesting part is that Warp is trying to make the terminal an agent operations surface. Not a better text box. Not a prettier shell. Not another place to paste a prompt. A control plane where humans describe work, agents execute inside a real development environment, and the product keeps the workflow close to commands, files, reviews, and feedback. That is why the announcement hit both Hacker News and GitHub Trending at the same time. On Hacker News, the main Warp story reached 370 points and 117 comments. The GitHub repo is sitting around 52,000 stars as of May 2, 2026. The disagreement in the comments is the useful signal: some developers see a credible agentic development environment taking shape, while others see a VC-backed terminal wrapping AI into yet another bloated product surface. Both sides are reacting to the same underlying shift. The terminal is no longer just where developers run commands. It is becoming one of the places where agents are managed. ## What Warp actually changed Warp says the client is now open source under AGPL, with its UI framework released under MIT. The repository describes Warp as an "agentic development environment, born out of the terminal." The company also says [OpenAI](/blog/openai-vs-anthropic-2026) is the founding sponsor of the new open source repository, and that its agentic workflows are powered by GPT models. For the larger agent workflow map, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they give the architecture and implementation context this piece assumes. That combination explains the mixed response. On one side, open sourcing the client directly addresses the biggest complaint Warp has carried for years: developers were being asked to trust a closed source terminal with an unusually privileged position in their workflow. A terminal sees commands, paths, environment behavior, project structure, and often enough context to make security-minded developers uncomfortable. On the other side, open source does not automatically make a product feel neutral. If the architecture still steers you toward a specific hosted agent platform, a specific account system, or a specific model vendor, then the practical trust question is not "can I read the source?" It is "can I own the workflow?" That is the part developers should care about. ## The terminal is a strange but logical agent surface At first glance, the terminal is an odd place to build an AI product. It is dense, unforgiving, and full of habits that have survived for decades because they are faster than graphical alternatives. But for [coding agents](/blog/what-is-an-ai-coding-agent-2026), the terminal has one huge advantage: it is already where verification happens. An agent that can edit files is only useful if it can also run the project, inspect failures, execute tests, read logs, call local scripts, and recover when the first pass is wrong. Those loops already live in the shell. The terminal has access to [the exact commands developers trust](/courses/building-clis/8): ```bash pnpm test pnpm build git diff rg "TODO" curl http://localhost:3000/api/health ``` That makes the terminal a better agent substrate than a detached chat panel. A chat panel can suggest. A terminal-native agent can suggest, run, inspect, revise, and prove. This is also why the category keeps converging. [Claude Code](/blog/what-is-claude-code-complete-guide-2026), Codex, Aider, OpenCode, Cursor agents, Zed threads, and Warp are all circling the same primitive: a supervised loop where an AI system has enough local context and tool access to do real work, while a human keeps authority over scope and merge decisions. The UX differs. The workflow shape is converging. ## The best argument for Warp The best version of the pro-Warp argument is not "AI belongs in the terminal." That is too broad. The better argument is: agent work needs an operations layer, and the terminal is one of the few places where that layer can stay honest. An agent operations layer needs a few things: 1. A task queue or thread model so work can be split into bounded units. 2. Direct visibility into commands, file edits, and failures. 3. A way to preserve context without turning every task into prompt soup. 4. Feedback loops that turn repeated failures into better local behavior. 5. Enough integration with git and review that changes can be evaluated before they land. Warp's announcement leans directly into that. It frames open source contribution itself as an agent-powered workflow: humans propose plans, agents help implement, and the repository becomes the training ground for better agentic development patterns. That is either very early or very important. Probably both. The most interesting part is not whether Warp wins. It is that the product thesis matches where serious AI coding is already going. Developers are not asking for a more charming autocomplete. They are asking for a system that can handle a scoped engineering task, produce a diff, run checks, and leave behind enough evidence for review. ## The best argument against Warp The skeptical HN read is also fair. Terminals are high-trust tools. Developers have spent years getting comfortable with boring, composable, local-first shells because those shells do not try to become platforms. When a terminal starts adding accounts, AI orchestration, hosted agents, team surfaces, and product-led workflows, some developers immediately see the wrong kind of abstraction. That skepticism is not nostalgia. It is a valid architectural instinct. The traditional terminal is powerful because it composes. It does not care whether you use Vim, Helix, Zed, [Cursor](/blog/what-is-cursor-ai-code-editor-2026), tmux, SSH, Docker, Make, Just, pnpm, uv, or a pile of local scripts. It is a thin layer over your tools. The fear is that an "agentic development environment" becomes a thick layer around your tools, and thick layers eventually want to own the workflow. There is also a licensing and governance question. AGPL source is meaningful, but community trust depends on more than license text. Developers will watch whether the open repo accepts real external contributions, whether local model support becomes first-class, whether hosted features remain optional, and whether the agent workflow works without surrendering too much control to a vendor platform. The open source move earns attention. It does not automatically earn trust. ## The real test is verification Most agentic coding tools still over-index on generation. They show the agent writing code, opening files, planning changes, or producing a patch. That is the easy part now. The hard part is verification. Can the tool tell whether the change actually works? Can it run the right tests? Can it understand a failing typecheck? Can it avoid celebrating a green command when the command did not test the affected path? Can it produce a diff small enough for a human to review? This is where terminal-native workflows have an advantage. They can keep the agent close to real evidence. A good agent loop should end with something like: ```bash git diff --stat pnpm typecheck pnpm test -- --run affected curl -s http://localhost:3000/api/health ``` That is also where products can become dangerous. If the interface hides too much detail, the agent can appear more competent than it is. The more autonomous the workflow becomes, the more important the receipts become. Logs, commands, diffs, test output, and review checkpoints are not implementation details. They are the trust layer. Warp's challenge is to make agent work feel faster without making it feel opaque. ## What developers should watch next If you are evaluating Warp after the open source move, do not judge it by whether the terminal looks polished. Judge it by whether the workflow respects developer control. The useful questions are practical: - Can you run meaningful agent workflows locally? - Can you bring your own model or harness? - Can you disable AI features without breaking the terminal experience? - Can you inspect exactly what the agent did and why? - Can you keep secrets, enterprise keys, and private repo context under your own rules? - Can you review every diff before anything is merged? - Can the open source community shape the roadmap, or is the repo mostly a visibility layer? Those questions matter more than whether Warp is "the future of terminals." The future is probably plural. Some developers will use Ghostty plus Claude Code. Some will use Zed threads. Some will use Cursor. Some will use Codex in a terminal. Some will use Warp because the integrated agent operations model is exactly what they wanted. The winning pattern is not one product. It is the loop. ## The take Warp going open source is a marker for where AI coding is heading. The category is moving away from isolated chat and toward operational surfaces where agents can be scoped, monitored, verified, and improved. That is the right direction. But the trust bar is higher for terminals than almost any other developer tool. A terminal has to be boring in the places where boring matters: command execution, local control, transparency, security, and exit rights. If Warp can keep those properties while making multi-agent work easier to manage, the open source move will matter. If it becomes a hosted AI platform wearing terminal clothing, developers will notice fast. The smart read is neither hype nor dismissal. Warp is testing whether the terminal can become the cockpit for agentic development. The answer will depend less on the launch post and more on whether the open repo proves the workflow in public. ## Sources - [Warp is now open-source](https://www.warp.dev/blog/warp-is-now-open-source) - [Warp on GitHub](https://github.com/warpdotdev/warp) - [Hacker News discussion](https://news.ycombinator.com/item?id=47936264) - [Warp GitHub repo discussion on Hacker News](https://news.ycombinator.com/item?id=47937349)

12 Tools in One Night: An Honest Overnight Agent Report

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The Setup At 11:47pm on April 28 I typed eight words into [Claude Code](/blog/what-is-claude-code-complete-guide-2026): For the broader agentic coding map, read [Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook](/blog/claude-code-agent-teams-subagents-2026) and [Why Skills Beat Prompts for Coding Agents in 2026](/blog/why-skills-beat-prompts-for-coding-agents-2026); they connect this article to the surrounding tool and workflow decisions. ``` /loop 10m improve the Developers Digest website overnight ``` Then I closed the laptop and went to bed. By 1:53am the orchestrator session had spawned dozens of [subagents](/blog/claude-code-sub-agents), opened 59 pull requests across 21 repositories, scaffolded 12 new private repos, drafted 6 blog tutorials, written 2 video scripts, generated 8 distribution packages, and shipped a 5-PR backend migration end to end. By the time I woke up, the morning brief sitting in my repo was the longest tally I have ever seen from a single prompt. This is not a Claude Code ad. The system did real work, but it also got things wrong, hit billing walls I had not budgeted for, and at one point fabricated a PR number that did not exist. The interesting story is the mix. So this is the candid version: what worked, what broke, and three lessons for anyone considering doing the same. ## The Orchestration Pattern The shape of the run was simple enough to describe in a paragraph and complicated enough that I am still untangling it. A parent orchestrator session held the loop. Every 10 minutes a cron-style tick fired off a planning step. The planner read the current state of the empire (24 apps under `developersdigest`, plus my standing rules), picked a batch of independent goals, and fanned out subagents in parallel to execute them. Some agents wrote code. Some scaffolded new repos. Some drafted blog posts. Some audited cross-repo consistency and filed reports. Each agent worked on its own branch in its own repo, opened a PR, tagged `@devin-ai-integration` for review, and exited. The parent never merged. That was deliberate. My standing rule is: branch, PR, tag Devin, never direct-push to main. The overnight session inherited that rule and held to it across 60 PRs without exception. The other rule it inherited was equally non-negotiable: nothing public on GitHub without my explicit say-so. Every one of the 12 new repos was created with `--visibility private`. I checked all of them in the morning. None had slipped. ## What Worked **Parallel fan-out scales further than I expected.** A single tick would routinely have 5 to 8 subagents running concurrently. One cycle scaffolded `mcp-lens`, `tracetrail`, and `cost-tape` in parallel while a separate group of agents added Sentry observability to four production apps and a third group enriched 817 detail pages with `generateMetadata` and JSON-LD across four directory sites. The bottleneck was never compute. It was always coordination, and most coordination was avoided by keeping each agent's blast radius tight: one repo, one branch, one PR. **The dogfood loop closed itself.** Three separate moments stood out. `dd-content-engine` PR #5 shipped a real Markdown to X / LinkedIn / newsletter fanout. By the next cycle, distribution agents were drafting their packages with the same fanout. `tracetrail`, scaffolded around 02:30 UTC, was wired into `overnight-agents` PR #4 within the hour as an "Open in TraceTrail" button on the runs page. `repo-postcard`, also new tonight, generated the 12 card PNGs that landed in `developers-digest-site` PR #47 for the new `/apps` entries. The system was building tools and using them in the same session. **Voice rules held under load.** My DevDigest voice rules are explicit: no em dashes, no emojis, no superlatives, no gradients, no "blazing fast." Across 6 blog drafts, 8 distribution packages, and 2 video scripts, the consistency was genuinely strong. I spot-checked 14 markdown files this morning and found zero em dashes and zero emojis. Whatever is in the system prompt for tone is sticking. **Reports were honest.** I asked for cross-repo audits across the empire and got four written deliverables, not code: `PRODUCT-IDEAS-2026-04-28.md`, `agent-ecosystem-2026-04-28.md`, `APPS-TIGHTEN-STATUS-clerk-neon-2026-04-28-v2.md`, `GA-IDEAS-2026-04-28.md`. The GA audit caught 18 apps hardcoding the same Google Analytics ID, which scaffolded the `dd-ga` repo to fix it. That is the loop I want from this kind of session: audit produces report, report seeds product, product fixes audit. **The Convex to Neon migration shipped end to end.** This was the most ambitious unit of work. Five sequential PRs in `dd-clipper` (#4 jobs storage, #6 apiKeys, #7 apiCredits, #8 apiUsageLog, #9 clips) walking the schema across one table at a time. The agent that owned this thread held the dependency order, rebased when it hit conflicts on #4, and produced a `docs: convex surface + neon migration plan` companion PR (#5) so the next person could audit the cutover. That sequence is documented separately in PR #49. ## What Did Not Work **The GitHub Actions billing wall.** Sometime around 03:15 UTC, every CI run on every open PR started failing with "The job was not started because recent account payments have failed or your spending limit needs to be increased." The org card had a billing failure. I did not know about it until I woke up. The agent kept opening PRs anyway because that was the right move, but it meant Devin had no CI signal to review against. Every one of the 60 PRs is currently red for a reason that has nothing to do with the code. Lesson: the orchestrator needs a billing check at the top of every loop, the same way it checks for `gh auth status`. **The gradient violation.** One agent, drafting a redesigned `/pro` waitlist landing in PR #37, introduced a hero with a gradient background. My rules say no gradients, full stop. A subsequent QA agent on a later cycle caught it, opened a follow-up commit on the same branch, and replaced the gradient with the solid `bg-cream` and a pink offset card. The system self-corrected, but only because I happen to run a recurring QA agent. Without that, the violation would have shipped to review and waited on Devin to flag. **The fake PR number.** This one is the most uncomfortable. Mid-run, an agent reported that it had opened "PR #51" against `developers-digest-site` for a sitemap improvement. The morning brief picked up the report. When I went to look, there was no PR #51. There was a branch with the work on it, sitting unpushed-as-PR. The agent had described an outcome that had not happened yet, the parent had taken the report at face value, and the brief had repeated it. I caught it because the PR table in the brief sorted by number and #51 was missing between #50 and #52. The actual PR was opened by hand once I confirmed the branch existed. I do not know yet whether the agent hallucinated the action or whether the `gh pr create` call failed silently and was misreported. Either way: trust nothing the orchestrator says about a PR number until you have seen it in `gh pr list`. **The rebase cascade.** `dd-clipper` PR #4 hit conflicts because two earlier cycles had touched the same `convex/schema.ts` region. The owning agent flagged it, but the rebase took a separate agent and a full cycle to resolve. During that window the four downstream PRs (#6, #7, #8, #9) were blocked. Sequential migrations and fan-out parallelism do not mix as cleanly as I thought. ## Three Lessons **1. Decompose for independence, not for parallelism.** The work that paralleled cleanly was work that touched separate repos or separate files. The work that did not (sequential migrations, schema changes, anything with implicit ordering) created queues and rebases. Before a loop starts, ask the planner to draw the dependency graph, then only fan out the leaves. **2. Verify every claim against the system of record.** Agents will report what they meant to do, what they think they did, and what they actually did, and these three are not always the same. Run a reconciliation pass at the end of every cycle: `gh pr list --json number,title --limit 100` and diff against the agent's claims. The fake PR #51 would have been caught instantly by this. **3. Pre-flight your invariants.** Billing was the one I missed. Other ones to check before starting an overnight: disk space on the host, `gh` rate limit budget, model context budget, any required secrets for the tasks the planner might pick, and whether `main` is already broken on any repo (one of mine, `dd-cron`, had a pre-existing `/api/health` build failure that masked a perfectly good favicon PR). If any invariant is red, the loop should pause and tell me, not push through. ## Honest Cost and Benefit The output is real. 12 private repos, each with a working scaffold and a README. 60 open PRs, each branched, tagged, and reviewable. 6 blog drafts at draft-true so I can edit before publishing. 817 newly-enriched SEO pages across the directory sites. A backend migration shipped in a single night that I had been dragging my feet on for two weeks. If I had to do this with my hands it would have taken a working week. The cost is not just dollars (the dollars I will know when the bill lands). The cost is the morning I am spending right now reconciling what was claimed against what is real, fixing the billing block, merging the boring PRs first, deciding which of the 12 new repos are worth keeping versus archiving. The agent did the producing. I have to do the curating, and curating 60 PRs is its own non-trivial day. The cost is also trust calibration. After tonight I trust the system more on bounded tasks (one repo, one PR, clearly scoped) and less on multi-step claims about its own outputs. I will run another loop next week, but with a reconciliation step inside the loop and a billing pre-flight at the top. If you want to see what came out of it, the [/apps page](/apps) lists the 12 new tools as coming-soon entries, the [comparison hub](/compare) was reorganized in PR #36, and the [10 tools announcement](/blog/ten-tools-for-agent-infrastructure) draft sits behind PR #42. For anyone trying this themselves: the loop works. It works better when you treat the agent like a junior engineer who is genuinely fast, occasionally wrong, and structurally incapable of admitting which is which without help. Build the help in. Then go to bed.

Agent Architecture: Building Multi-Step AI Workflows That Survive Production

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## What actually makes something an agent A chatbot answers. An agent decides. The line is clear in theory and blurry in code, so it helps to anchor on the loop. An agent runs a loop where the model picks the next action, a runtime executes it, and the result feeds back into the next decision. That loop is the only thing that separates a multi-step Claude workflow from a glorified `if/else` over a single completion. Everything else - tools, memory, planning, reflection - is decoration on top of that core. If your "agent" runs three sequential prompt calls in a fixed order with no branching, that is a pipeline. Pipelines are great. They are not agents. The reason this matters is operational. Pipelines have predictable cost and latency. Agents have a probability distribution over both, because the model controls the trip count. Treat them differently in production or you will be surprised by your bill. Watch the [DevDigest video on building your first AI agent](https://www.youtube.com/@DevelopersDigest) for the visual walk-through. The rest of this post is the architecture you bolt around that loop once it leaves localhost. ## The four loop patterns you actually use Almost every production agent I have shipped collapses into one of four shapes. **Pattern A: simple loop.** Plan, act, observe, repeat. No reflection step. Cheap, fast, and works for tasks where the model can recover from a bad tool call by trying a different one. Most "research this URL" or "summarize this codebase" agents live here. **Pattern B: loop with reflection.** Same as A, but every N iterations the agent gets prompted with "you have done X, Y, Z so far. Are you on track? Should you change strategy?" Reflection is expensive (extra round trip, extra tokens, extra cache miss) but pulls success rates up sharply on any task that involves multi-hop reasoning. Use it when the cost of a wrong path is high. **Pattern C: manager + workers.** A manager agent decomposes the goal into subtasks and dispatches them to worker agents. Workers report back. Manager assembles results. This is the pattern [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s own engineering team uses for parallel research. The win is parallelism. The cost is coordination overhead, which is real. **Pattern D: hierarchical with verification gates.** Same as C, but the manager runs each worker output through a verifier before accepting it. The verifier is usually a smaller model (Haiku verifying Sonnet) or a deterministic check. This is the pattern that survives at 10+ steps without the [agent reliability cliff](/blog/the-agent-reliability-cliff) eating you alive. Here is the simple loop with the Anthropic TypeScript SDK. Real, runnable, no pseudocode. ```typescript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const tools: Anthropic.Tool[] = [ { name: "search_docs", description: "Search internal documentation for a query", input_schema: { type: "object", properties: { query: { type: "string" } }, required: ["query"], }, }, { name: "finish", description: "Call when the task is complete", input_schema: { type: "object", properties: { answer: { type: "string" } }, required: ["answer"], }, }, ]; async function executeTool(name: string, input: any): Promise { if (name === "search_docs") { return await searchDocs(input.query); } throw new Error(`unknown tool: ${name}`); } async function runAgent(goal: string, maxSteps = 8) { const messages: Anthropic.MessageParam[] = [{ role: "user", content: goal }]; for (let step = 0; step < maxSteps; step++) { const response = await client.messages.create({ model: "claude-sonnet-4-5", max_tokens: 4096, tools, messages, }); messages.push({ role: "assistant", content: response.content }); if (response.stop_reason === "end_turn") return messages; const toolUses = response.content.filter( (b): b is Anthropic.ToolUseBlock => b.type === "tool_use" ); if (toolUses.length === 0) return messages; const toolResults: Anthropic.ToolResultBlockParam[] = await Promise.all( toolUses.map(async (tu) => { try { const result = await executeTool(tu.name, tu.input); return { type: "tool_result", tool_use_id: tu.id, content: result }; } catch (err) { return { type: "tool_result", tool_use_id: tu.id, content: `error: ${(err as Error).message}`, is_error: true, }; } }) ); messages.push({ role: "user", content: toolResults }); if (toolUses.some((t) => t.name === "finish")) return messages; } throw new Error("agent exceeded max steps"); } ``` Three things make this production-shaped instead of demo-shaped. The hard step cap, the explicit `finish` tool that lets the model signal completion (don't trust `end_turn` alone, the model lies about being done), and the `is_error` flag on tool results so the model knows when something failed instead of returning silent garbage. ## State management is where agents go to die The single biggest difference between an agent demo and an agent in production is what happens to context. A demo runs for five turns. A production agent runs for forty. By turn twenty your messages array is 80k tokens of tool calls, partial results, and reasoning. Three things break. First, latency. Every turn re-uploads the entire history. Without [prompt caching](/blog/prompt-caching-claude-api-production-guide) you pay full input cost on every step, and the call time creeps from two seconds to fifteen. Second, attention. Models are demonstrably worse at long contexts. The instruction you put in the system prompt at turn one is competing with 60k tokens of tool noise by turn twenty. The model starts forgetting constraints. Third, the cost compounds geometrically. A 20-step agent with no caching [costs](/blog/ai-coding-tools-pricing-comparison) roughly 10x what the same agent with caching costs, because each turn pays for everything before it. The fix is two patterns layered together. **Prompt caching on the system prompt and tool definitions.** Anthropic's prompt cache cuts cached read costs to 10 percent of normal input. For an agent that reuses the same tool schema across thirty turns, this is the single most impactful change you can make. Set `cache_control: { type: "ephemeral" }` on your tools array (final element) and on the system message. **Summarization checkpoints.** Every N steps (we use 10), have the agent compress its own history. Replace the messages array with a single user message: "Summary of your work so far: ..." plus the most recent two turns. Lossy but necessary. The trick is making the summary include enough state for the agent to keep going - what it was trying to do, what it has tried, what failed, what is next. ```typescript async function compactHistory( messages: Anthropic.MessageParam[] ): Promise { if (messages.length < 20) return messages; const summary = await client.messages.create({ model: "claude-haiku-4-5", max_tokens: 1024, messages: [ ...messages, { role: "user", content: "Summarize what you have done so far in 200 words. Include the goal, completed steps, current blockers, and the next planned action.", }, ], }); const summaryText = summary.content .filter((b): b is Anthropic.TextBlock => b.type === "text") .map((b) => b.text) .join(""); return [ { role: "user", content: `Resuming task. Prior progress:\n\n${summaryText}` }, ...messages.slice(-4), ]; } ``` Use Haiku for the summary. It is dramatically cheaper, the summary doesn't need Sonnet-level reasoning, and the compaction is now a fixed-cost operation regardless of history length. ## Error handling: the part everyone skips There are four error categories in an agent and they need different responses. **Tool execution errors.** The tool ran and threw. Network failure, permission denied, malformed input. These are recoverable. Return the error string back as a tool result with `is_error: true`. The model will usually retry with adjusted input. If the same tool fails three times in a row with similar errors, escalate. **Invalid tool calls.** The model called a tool with invalid input shape. Schema validation should catch this before execution. Return a structured error explaining what was wrong. The model corrects on the next turn 90 percent of the time. **API errors from Anthropic.** Rate limits, 5xx, timeouts. These are infrastructure problems. Retry with exponential backoff and jitter. We wrote up the full pattern in [Claude API reliability: error handling best practices](/blog/claude-api-reliability-error-handling). **Logical errors.** The agent is doing the wrong thing. Maybe stuck in a loop calling the same tool. Maybe wandering into off-topic territory. These are not recoverable with a retry. They need a circuit breaker - if step count exceeds budget, or the same tool is called with the same input twice in a row, hard-stop and return what you have. The loop-detection circuit breaker is the one most teams skip and the one that saves the most money. Three lines of code, one Set, prevents the runaway agent that calls `search_docs("hello")` 50 times until your context window explodes. ```typescript const callSignatures = new Set(); for (const tu of toolUses) { const sig = `${tu.name}:${JSON.stringify(tu.input)}`; if (callSignatures.has(sig)) { throw new Error(`loop detected: ${sig} called twice`); } callSignatures.add(sig); } ``` ## Decomposition: how to know when an agent is done A bad agent doesn't know when to stop. A good agent has explicit success criteria baked into the prompt. This is the single highest-leverage prompt engineering change for multi-step work. The pattern is to give the model an explicit `finish` tool with a structured output, and tell it in the system prompt exactly when to call it. "Call finish when you have a complete answer to the user's question, with citations to at least two sources." The model then has a concrete target, not a vibe. For decomposition, the manager-worker pattern works best when the manager produces a static plan first, then dispatches in parallel. Dynamic dispatch (manager picks next task based on previous worker output) sounds smart but introduces sequential dependencies that kill throughput. Static plan, parallel dispatch, sequential merge. ```typescript async function managerPlan(goal: string): Promise { const response = await client.messages.create({ model: "claude-sonnet-4-5", max_tokens: 2048, system: "You are a planner. Decompose the goal into 3-5 independent subtasks. Return JSON array of strings, no other output.", messages: [{ role: "user", content: goal }], }); const text = response.content.find((b): b is Anthropic.TextBlock => b.type === "text")?.text ?? "[]"; return JSON.parse(text); } async function fanOut(goal: string) { const subtasks = await managerPlan(goal); const results = await Promise.all(subtasks.map((t) => runAgent(t, 8))); return results; } ``` `Promise.all` is doing real work here. Three workers running in parallel cuts wall-clock time roughly 3x compared to sequential. For research-style tasks this is the difference between a 90 second response and a 30 second one. ## Production at scale: what breaks past 100 concurrent agents Once you are running real agent traffic, three things bite. **Rate limit shape.** Anthropic rate limits are per-organization, measured in tokens per minute. A burst of 100 agents starting simultaneously will hammer the limit during their first turn (when input tokens are smallest) and then again in waves. Smooth this with a token bucket on your side. Don't trust the SDK retries to handle it - they will, but you will burn budget on retries that could have been spaced out. **Per-agent cost variance.** Average cost per agent run might be $0.40, but the p99 will be $4.00, and the p99.9 will be $40 if you don't have a hard ceiling. Set a per-agent token budget. When the cumulative input + output tokens for one run exceeds the cap, terminate. We track this on every run with [agent-finops](/projects), our cost observability dashboard - watching the p99 line is the only way to catch a runaway before the bill arrives. **Replay and debugging.** The hardest agent bugs are the ones that happened in production three days ago and you can't reproduce. The fix is logging every step with full input, output, and tool result. Storage is cheap. We use [tracetrail](/projects) to replay agent runs step by step against the same prompts and inputs, which is how we usually figure out whether a regression was the model, the tool layer, or the prompt itself. The full architecture for a production-ready Claude agent fits in maybe 300 lines of TypeScript. The harder work is the operational scaffolding around it - cost limits, replay, monitoring, summarization. Skip those and the loop runs fine on day one and ruins your week on day thirty. If you want to see this stack working end to end, the [DevDigest YouTube channel](https://www.youtube.com/@DevelopersDigest) has the build-along where we wire up Sonnet 4.5, prompt caching, the manager-worker fan-out, and the replay layer in a single Next.js app. The pattern is the same whether you are running one agent or a thousand. The discipline scales with the count. ## FAQ ### What is the difference between an agent and a pipeline? A pipeline runs a fixed sequence of prompts in order with no branching. An agent runs a loop where the model picks the next action, executes it, and feeds the result back into the next decision. The distinction matters operationally because pipelines have predictable cost and latency, while agents have a probability distribution over both since the model controls the loop count. ### How many steps can a production agent run before it breaks down? Most agents start degrading past 15-20 steps due to context length issues, attention drift, and compounding latency. Without prompt caching and history summarization, a 20-step agent costs roughly 10x what one with caching costs. The practical ceiling depends on your caching strategy and summarization checkpoints - with both, you can push to 40+ steps reliably. ### Which loop pattern should I use for my agent? Use Pattern A (simple loop) for straightforward tasks like URL research or codebase summarization where the model can recover from errors by trying different tool calls. Use Pattern B (loop with reflection) when wrong paths are expensive and you need the model to self-correct. Use Pattern C (manager + workers) for parallelism. Use Pattern D (hierarchical with verification) for anything over 10 steps where the reliability cliff would otherwise kill you. ### Why do I need an explicit finish tool? Models lie about being done. Relying on `end_turn` alone leads to agents that declare victory prematurely or trail off into irrelevant reasoning. An explicit `finish` tool with structured output gives the model a concrete target and lets you define exactly what completion means - like "call finish when you have a complete answer with citations to at least two sources." ### How do I prevent runaway agent costs? Three controls: a hard step cap (set `maxSteps` and enforce it), a per-agent token budget (terminate when cumulative input + output exceeds the cap), and loop detection (if the same tool is called with the same input twice, hard-stop). The loop-detection circuit breaker is three lines of code and saves the most money by catching the agent that calls `search_docs("hello")` 50 times. ### What is the best way to handle long agent histories? Two patterns layered together. First, use Anthropic's prompt caching on the system prompt and tool definitions - this cuts cached read costs to 10% of normal for the constant parts. Second, run summarization checkpoints every 10 steps using Haiku to compress the history into a summary that includes the goal, completed steps, current blockers, and next planned action. ### How do I debug agent failures that happened in production? Log every step with full input, output, and tool results. Storage is cheap, debugging without logs is expensive. The hardest bugs are ones you cannot reproduce, so replay capability is essential. Replay tools let you re-run agent sessions step by step against the same prompts and inputs to figure out whether a failure was the model, the tool layer, or the prompt. ### What is the manager-worker pattern and when should I use it? The manager agent decomposes a goal into subtasks and dispatches them to worker agents running in parallel. Workers report back, and the manager assembles results. Use it when you need parallelism - three workers running `Promise.all` cuts wall-clock time roughly 3x compared to sequential. The cost is coordination overhead, so it only pays off when subtasks are genuinely independent.

OpenAI Agents SDK Evolution: What Ships in Production

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

I rebuilt my customer support agent on the new [OpenAI Agents SDK](/blog/openai-agents-sdk-typescript) and discovered three undocumented foot-guns in the first week. The agent now runs noticeably faster, holds context across longer sessions, and uses filesystem tools the same way Codex agents do. It also nearly nuked our staging knowledge base on day two because of an interaction between sandbox lifetime and memory writes that I will detail below. This is the writeup of what shipped, what is genuinely better, and what to watch for if you are migrating an existing agent. ## What Changed And Why It Is A Real Upgrade The previous Agents SDK was already capable. You could orchestrate tool calls, hand off between agents, and run [multi-agent workflows](/blog/building-multi-agent-workflows-claude-code) with reasonable observability. What it could not do natively was hold meaningful state between sessions or operate over a real filesystem the way a Codex agent does. For the larger agent workflow map, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); they give the architecture and implementation context this piece assumes. The new SDK ships three primitives that close those gaps. The first is configurable memory. Agents now have first-class short-term and long-term memory tiers, with explicit scoping (per session, per user, per organization) and explicit retention policies. You no longer roll your own vector store integration for "remember what this customer told us last week". The second is sandbox-aware orchestration. Tool execution can target specific sandbox environments with their own lifetime, file state, and resource limits. Multi-agent workflows can pass a sandbox between agents instead of just passing messages, which is the closest thing to a workspace handoff that any major SDK currently supports. The third is filesystem tools borrowed directly from the Codex stack. `read_file`, `write_file`, `apply_patch`, `list_dir`, and `run_in_sandbox` are now native primitives. Agents can manipulate files the same way Codex does, which makes building "agents that produce artifacts" much cheaper than it used to be. These three together are what makes the new SDK a real upgrade rather than an incremental refresh. Memory plus sandbox plus filesystem is the ingredient list for agents that do real work over time. ## Configurable Memory In Practice The memory API has two tiers and the distinction matters. Short-term memory is per-session, ephemeral, and bounded. It is automatically managed: the SDK summarizes older turns when the context window fills, and you can configure the summarization aggressiveness. Most teams should leave this on default. Long-term memory is persistent, explicitly scoped, and explicitly written. You decide what to store, when to store it, and who owns the scope. The SDK exposes it as a tool the agent can call, which means the agent itself can choose to remember something. This is more powerful and more dangerous than it sounds. A minimal example with the Python SDK: ```python from openai import OpenAI from openai.agents import Agent, Memory client = OpenAI() memory = Memory( scope={"user_id": "u_8423", "org_id": "org_acme"}, retention="90d", tier="long_term", ) support_agent = Agent( name="support", model="gpt-5.3-codex", instructions=( "You are a customer support agent for Acme. " "Use long-term memory to remember user preferences and past issues. " "Never write secrets or PII into memory." ), memory=memory, tools=["filesystem", "code_interpreter"], ) result = support_agent.run( input="Customer u_8423 says: my dashboard is showing yesterday's data again. " "Check the cache config and remember my preference for east coast timezone." ) print(result.output_text) ``` Two things worth noting. First, the `scope` is what gives you privacy boundaries. If you scope memory per user, you cannot accidentally read another user's history. Get this wrong and you have a bug class that is genuinely hard to detect in testing because it surfaces only at scale. Second, the `retention` policy is enforced server side. You do not need to write a cron job to expire old memories. For agents that produce artifacts and need to track them over time, I run a versioned filesystem in front of the memory tier with [agentfs](https://agentfs.developersdigest.tech). Memory tracks intent and preferences. agentfs tracks the actual files the agent has written, with audit trails. The combination is what makes incident investigation possible after the fact. ## Sandbox-Aware Orchestration Classic tool-use treats every tool call as stateless. You call a function, it returns a value, the agent moves on. This breaks down the moment you want an agent to actually do work over time, like running a build, modifying files, then running tests against the modified files. Sandbox-aware orchestration solves this by making the sandbox itself a first-class entity that lives across tool calls and can be passed between agents. ```python from openai.agents import Sandbox, Agent, Workflow sandbox = Sandbox.create( image="python-3.12-slim", timeout_seconds=900, memory_mb=2048, ) planner = Agent(name="planner", model="gpt-5.3", instructions="Plan tasks.") implementer = Agent( name="implementer", model="gpt-5.3-codex", instructions="Execute the plan in the provided sandbox.", tools=["filesystem", "shell"], ) verifier = Agent( name="verifier", model="gpt-5.3-codex", instructions="Run tests and report results.", tools=["shell"], ) workflow = Workflow( agents=[planner, implementer, verifier], sandbox=sandbox, handoff="sequential", ) result = workflow.run(input="Add a /healthz endpoint to the FastAPI app and verify it.") ``` The sandbox is shared across all three agents. The planner produces a plan, the implementer writes files into the sandbox, the verifier runs tests against those files. No serialization of state through messages, no rebuilding the workspace at each handoff. This is the orchestration model that finally feels right. There is a real architectural question about whether you should be running orchestration through the SDK at all or running it externally. Multi-agent workflows that span more than a few steps, especially ones that touch external systems, are often easier to reason about as explicit DAGs you control. The framing I use in [DD Orchestrator](https://orchestrator.developersdigest.tech) is that SDK orchestration is right when the work is contained inside one sandbox or one model call graph, and external orchestration is right the moment you have to coordinate with services outside the agent boundary. For my support agent the SDK is exactly the right tool. For a billing reconciliation pipeline that touches three databases and a Stripe webhook queue, it is not. ## Filesystem Tools Borrowed From Codex The filesystem tools are the dark horse of the release. They are powerful, they are dangerous, and they are the right primitive for the kind of agents people actually want to build. When this is a superpower: any agent that needs to produce a structured artifact. Code, configuration files, generated reports, image manifests. Giving the agent direct filesystem access lets it iterate, verify its own output by reading it back, and apply patches without you having to wrap every operation in custom tool code. When this is a footgun: any agent that has filesystem access and does not have hard boundaries on what it can read or write. The Codex tools are deliberately powerful. `apply_patch` will apply a patch to anything in the sandbox. If the sandbox has access to your knowledge base, the agent can rewrite your knowledge base. Ask me how I know. The countermeasures are simple but non-negotiable. Mount only the directories the agent needs. Use a read-only mount when the agent does not need to write. Set explicit byte limits on writes. Log every write and replay them in your tracing system before deploying changes that touch production data. For the architecture diagram showing the old SDK message-passing model versus the new sandbox-aware model, the [DevDigest YouTube walkthrough](https://www.youtube.com/@DevelopersDigest) is the clearest visual reference I have seen. It is also where I show the memory-tier debugging session that I will not be able to do justice to in text. ## Three Undocumented Gotchas I Hit These are the things that did not make it into the changelog and that you should know before you ship. The first is a race condition between memory writes and sandbox shutdown. If you write to long-term memory inside a tool call, then the sandbox terminates before the write is acknowledged, the write may or may not land. The SDK does not currently expose a sync primitive for this. My fix was to write to memory only at the end of the agent run, after the sandbox has closed cleanly. If you write mid-flight, you need to await the memory acknowledgment explicitly. The second is token bloat from memory recall. By default, the SDK will inject up to roughly 8k tokens of recalled memory into the context per turn. For agents that run for many turns, this compounds quickly. I found my support agent spending 30% of its context budget on recalled memory by turn ten, with most of the recall being irrelevant to the current question. The fix is to constrain recall with explicit query hints in the agent instructions and to lower the recall token budget in the memory configuration. The default is too generous for production use. The third is eval drift across SDK versions. The SDK is moving fast and the same agent code can behave subtly differently across patch releases. Tool selection, planning style, and recall behavior have all shifted in releases that did not change the API surface. Pin your SDK version. Run your eval suite before bumping. Tag the eval baseline in your version control. This is not unique to the OpenAI SDK but the rate of change here makes it more pressing than usual. ## Migration Plan For Existing Agents If you have an agent on the previous SDK, here is the rollout I would recommend. Start with a flag-gated branch. The new SDK can run alongside the old one, so route 5% of traffic to the new agent and watch your metrics. Latency, cost, and error rate are the obvious ones. Memory hit rate and tool error distribution are the less obvious ones that will tell you whether the new primitives are actually helping. Add observability before you add features. The new SDK has more moving parts than the old one. You want to see which memories are being recalled, which tools are being chosen, and how long each step is taking. Without that, you will not be able to tell why the agent is acting differently when it does. Roll forward gradually. Move from 5% to 25% to 50% over a week, not over an hour. The interesting failure modes (memory drift, sandbox timeouts, recall token bloat) only show up under sustained traffic. Keep the rollback path warm. The old SDK works. If something goes wrong, you want to be able to flip back in one config change, not a code revert. Treat the migration as a feature flag, not a refactor. The new Agents SDK is a real upgrade, and the primitives, memory, sandbox-aware orchestration, filesystem tools, are the right primitives for the agents people actually want to ship in 2026. The foot-guns are real but manageable. If you have an agent in production today, the question is not whether to migrate but when, and the answer for most teams is "this quarter, behind a flag, with your eval suite watching".

OpenAI Apps SDK: Building MCP UIs Inside ChatGPT

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

Apps SDK is [OpenAI](/blog/openai-vs-anthropic-2026)'s answer to the question "what does a third-party app inside ChatGPT actually look like." The technical answer is MCP plus a UI runtime that renders inline in the ChatGPT surface. The practical answer is that you can now ship something that feels like a native ChatGPT feature, addressed via natural language, with a real interface, distributed through OpenAI's directory. I shipped a real Apps SDK app the week the SDK opened up. It is a "weekly DevDigest brief" app that pulls the most-read posts from the DevDigest backend and renders them as an interactive card in ChatGPT. Building it took about a day of focused work. Most of that day was spent on three gotchas that the docs do not cover well: auth, distribution, and telemetry. This post walks through the full build with an emphasis on those three. ## What Apps SDK actually is The architecture has two pieces. One is an MCP server you host. The other is a UI runtime that ChatGPT renders on your behalf when the user invokes your app. For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article. The MCP server is a standard MCP server. If you have built one before, you already know most of the moves: a list of tools, a list of resources, request handlers that return structured data. The thing that is new is that some of your tool responses can include UI directives. ChatGPT picks up those directives and renders an interactive component inline in the chat surface, parameterized by the data your tool returned. The UI runtime is constrained on purpose. You do not get arbitrary HTML. You get a component vocabulary defined by Apps SDK: cards, lists, buttons, forms, simple charts, and a handful of layout primitives. The constraint is the point. Apps render consistently across ChatGPT clients without you shipping a webview, and OpenAI can ensure the UI cannot do anything unsafe inside the ChatGPT surface. The mental model that worked for me is this. MCP tools are how your app does things. UI directives are how your app shows things. The user's natural-language prompt is how your app gets invoked. Distribution is how your app gets discovered. ## Project layout Here is the file structure I landed on after one round of refactoring. ``` weekly-brief-app/ package.json tsconfig.json src/ server.ts # MCP server entrypoint tools/ get_brief.ts # Tool that returns the brief data subscribe.ts # Tool that toggles user subscription state ui/ brief_card.ts # UI directive for the brief subscribe_form.ts state/ store.ts # Per-user state (KV in production) auth/ session.ts # User identity + token verification manifest.json # Apps SDK manifest for distribution ``` The split that matters is `tools/` for logic and `ui/` for the directive payloads. Keeping them separate means you can unit-test the data path without spinning up the UI runtime, and you can iterate on UI without changing tool signatures. The first iteration of the app had logic and UI in the same file and got messy fast. The MCP server entry is short. ```ts import { McpServer } from "@modelcontextprotocol/sdk/server"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/transport/stdio"; import { getBrief } from "./tools/get_brief.js"; import { subscribe } from "./tools/subscribe.js"; const server = new McpServer({ name: "weekly-brief", version: "0.1.0", }); server.tool(getBrief); server.tool(subscribe); const transport = new StdioServerTransport(); await server.connect(transport); ``` The tool handler is where the UI directive comes in. ```ts import { defineTool } from "@modelcontextprotocol/sdk/server"; import { briefCard } from "../ui/brief_card.js"; import { fetchBriefForUser } from "../data.js"; export const getBrief = defineTool({ name: "get_weekly_brief", description: "Fetch this week's DevDigest brief for the current user. Returns the top posts and lets the user open or save them inline.", inputSchema: { type: "object", properties: { week: { type: "string", description: "ISO week, e.g. 2026-W17" }, }, }, async handler({ week }, ctx) { const userId = ctx.user.id; const data = await fetchBriefForUser(userId, week); return { content: [{ type: "text", text: `Brief for ${week}` }], ui: briefCard(data), }; }, }); ``` The `ui` field on the tool response is what ChatGPT renders. The text content is the fallback for clients that do not render UI. Both are required. Skip the text content and your app breaks the moment a user invokes it from a client that does not support the runtime. ## Building a real app The brief app does three things: fetch the week's top posts for the signed-in user, let the user click through to read them, and let the user toggle whether they want the brief delivered to their email inbox each week. The brief card directive looks like this. ```ts import type { UiDirective } from "@openai/apps-sdk"; export function briefCard(data: BriefData): UiDirective { return { type: "card", title: `DevDigest brief for ${data.week}`, body: [ { type: "list", items: data.posts.map((p) => ({ title: p.title, subtitle: p.excerpt, actions: [ { type: "open_url", label: "Read", url: p.url }, { type: "tool_call", label: "Save", tool: "save_post", args: { id: p.id } }, ], })), }, { type: "button", label: data.subscribed ? "Unsubscribe" : "Subscribe to weekly email", action: { type: "tool_call", tool: "subscribe", args: { state: !data.subscribed } }, }, ], }; } ``` The card-with-list shape is the workhorse of Apps SDK UIs. Most apps end up rendering some variant of this. The actions array is the part that makes it feel interactive. `open_url` opens a link in a new surface. `tool_call` re-invokes one of your MCP tools, optionally with a fresh UI directive in response. That round trip is how you build interactive flows without writing client-side code. ## Auth and state Auth is the part that bit me hardest. The Apps SDK runtime gives your tool handler a `ctx.user` object, but the identity in that object is scoped to ChatGPT, not your app. To map a ChatGPT user to a user in your own product, you need to do an explicit linking flow the first time the user invokes your app. The pattern that worked is a deferred-link tool. The first invocation of the brief tool checks whether the ChatGPT user ID is linked to a DevDigest account. If not, it returns a UI directive with a one-time-code link button that opens DevDigest's login flow with a `link_token` query param. The DevDigest backend completes the link by associating the ChatGPT user ID with the DevDigest account and reporting back via webhook to the Apps SDK runtime. ```ts async function ensureLinked(ctx: ToolContext): Promise { const link = await store.getLink(ctx.user.id); if (link) return link; const linkToken = await store.createLinkToken(ctx.user.id); return null; // caller renders link UI } export const getBrief = defineTool({ // ... async handler(args, ctx) { const link = await ensureLinked(ctx); if (!link) { return { content: [{ type: "text", text: "Link your DevDigest account to continue." }], ui: linkPromptCard(linkToken), }; } // ... fetch brief }, }); ``` State is simpler. Apps SDK gives you no built-in storage, which is the right call. Use whatever KV or database you already have. I keep the link table and the per-user subscription state in the existing DevDigest Postgres instance and access it through the same data layer the rest of the product uses. The MCP server is a thin shell over our existing API. For teams that do not have an existing backend, [MCPaaS](https://mcpaas.developersdigest.tech) gives you a hosted MCP runtime with a bundled KV store and the auth-link plumbing already wired up. It pairs nicely with Apps SDK clients because the deployment story is "push your tool handlers and you are done." ## Distribution Distribution is the next big surprise. You do not just ship an Apps SDK app and have it appear in ChatGPT. You publish to the OpenAI directory, your app gets reviewed, and then it shows up in search. The manifest is the artifact that drives discovery. ```json { "name": "DevDigest Weekly Brief", "slug": "devdigest-brief", "description": "Get your personalized weekly DevDigest brief inside ChatGPT.", "icon": "https://cdn.devdigest.com/apps/brief-icon.png", "tools": ["get_weekly_brief", "save_post", "subscribe"], "discovery": { "keywords": ["devdigest", "weekly brief", "developer news"], "example_prompts": [ "What's in this week's DevDigest brief?", "Show me the latest from DevDigest" ] }, "auth": { "type": "linked_account", "link_url": "https://devdigest.com/apps-sdk/link" } } ``` Two non-obvious notes. First, `example_prompts` is what ChatGPT uses to learn when to suggest your app. Generic prompts get drowned out. Specific, brand-anchored prompts work much better. Second, the icon URL has to be served with permissive CORS or the directory listing breaks silently. If you have shipped MCP servers before, you know that discoverability is the whole game. I learned this running [MCP Directory](https://mcp.developersdigest.tech), which now indexes more than 200 servers. The same lesson applies on Apps SDK: a good description, specific example prompts, and a clean icon move the needle more than features do. ## Telemetry and iteration The last piece is figuring out what users actually do. Apps SDK does not give you UI-level telemetry out of the box. You have to instrument it yourself by logging tool invocations, including tool calls triggered from UI buttons, into your own analytics. I wrap every tool handler in a small middleware that emits a structured event before and after. ```ts function withTelemetry(tool: T): T { const original = tool.handler; tool.handler = async (args, ctx) => { const start = Date.now(); await analytics.track({ event: "apps_sdk.tool_invoked", tool: tool.name, user_id: ctx.user.id, args, }); try { const result = await original(args, ctx); await analytics.track({ event: "apps_sdk.tool_completed", tool: tool.name, latency_ms: Date.now() - start, ui_rendered: !!result.ui, }); return result; } catch (err) { await analytics.track({ event: "apps_sdk.tool_failed", tool: tool.name, error: String(err), }); throw err; } }; return tool; } ``` The event I look at most is the funnel from "first invocation" to "linked account" to "second invocation." That funnel tells me whether the auth-link flow is working in practice. The first version of the app had a 38 percent drop-off on the link step, which I traced to the link button copy being unclear. Rewriting the button label from "Link account" to "Connect DevDigest" lifted completion to 71 percent. I shipped the full build walkthrough on the [DevDigest YouTube channel](https://www.youtube.com/@DevelopersDigest), with the file-tree screenshot and the deployed app demo. The repo is private until I clean up the auth-link flow for general consumption. If you are building your first Apps SDK app, the order of operations I would recommend is: get a single tool returning a card, ship it locally, then layer auth, then telemetry, then distribution. Trying to do all four at once is how the gotchas compound.

Astro vs Next.js 16: Which to Choose in 2026

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

The framework debate in 2026 is not about React versus the world. It is about how much JavaScript your users should have to download. Astro 5 ships a typical page in 0 to 15 kilobytes of client JavaScript. Next.js 16 ships the same page in 85 to 250 kilobytes. That ratio decides almost everything else. This post is not a hype piece. Both frameworks are excellent at what they were built for. The mistake teams keep making is choosing the wrong one for the job, and then spending six months fighting the framework instead of shipping. If you read [our 2026 stack guide for Next.js AI apps](/blog/nextjs-ai-app-stack-2026) and walked away thinking "every site should be Next.js," this is the corrective. ## Quick Verdict Pick Astro 5 when the site is mostly content. Marketing pages, documentation, blogs, course sites, landing pages, anything you would describe as "publishing." Astro will be faster, cheaper to host, easier to deploy, and easier to maintain. Pick Next.js 16 when the site is mostly application. Authenticated dashboards, multi-tenant SaaS, anything with persistent client state, anything that depends on the React ecosystem (TanStack Query, Radix, shadcn/ui, the [Vercel AI SDK](/blog/vercel-ai-sdk-guide)). Next.js will be slower for first paint but dramatically faster to build with. The boundary is fuzzy. There are content sites that use Next.js well and applications that use Astro well. But if you start from "what is the page mostly doing," you will pick correctly 90 percent of the time. ## What Changed in 2026 Both frameworks shipped major releases in the past year that materially change the comparison. **Astro 5** introduced the Content Layer API and Server Islands. The Content Layer turns every content source - markdown, MDX, headless CMS, database - into a typed collection your build pipeline understands. Server Islands let you render specific components on the server on demand while the rest of the page stays static. Combined, they remove the biggest historical complaint about Astro: that it could not handle "mostly static, partially dynamic" pages without ejecting to SSR. **Next.js 16** doubled down on the App Router, removed the Pages Router from new projects, made Turbopack the default bundler, and shipped Partial Prerendering (PPR) as stable. PPR lets a single route mix static shell rendering with streamed dynamic content out of the box. The framework now assumes you are building a React Server Components application and stops apologizing for the bundle size. Cloudflare also acquired Astro in early 2026, which matters because Astro's deployment story is now first-class on Cloudflare Workers and Pages, with native edge runtime support and zero cold starts on most routes. ## The JavaScript Bundle Reality The single most important number in this comparison is the size of the JavaScript payload your users download to view a page. Here is what an empty marketing homepage actually ships in production builds, measured on a Pixel 8 over throttled 4G: | Framework | First Load JS | Largest Contentful Paint | Time to Interactive | |-----------|---------------|--------------------------|---------------------| | Astro 5 (no islands) | 0 KB | 0.6 s | 0.6 s | | Astro 5 (one React island) | 14 KB | 0.8 s | 0.9 s | | Next.js 16 (App Router, RSC) | 92 KB | 1.4 s | 1.7 s | | Next.js 16 (with Vercel AI SDK) | 187 KB | 1.9 s | 2.4 s | Astro pages start with zero client JavaScript. The HTML and CSS render the page. If you sprinkle in interactive components, only those components hydrate, and only with the JavaScript they need. Next.js, even with Server Components, still ships a React runtime and routing layer to every page. This is not a knock on Next.js. The runtime cost buys you instant client-side navigation, persistent layout state, and the entire React ecosystem. For an application, that is worth it. For a blog, it is pure overhead. ## Architecture: Islands vs Server Components Astro uses the islands architecture. The page is a static HTML document. Interactive parts are explicitly opted in with a directive on each component: ```astro --- // src/pages/index.astro import Hero from "../components/Hero.astro"; import Counter from "../components/Counter.tsx"; import Newsletter from "../components/Newsletter.tsx"; --- ``` Three components, three different hydration strategies. The hero is static. The counter only loads JavaScript when it scrolls into view. The newsletter form loads when the browser is idle. You can mix React, Vue, Svelte, and Solid components on the same page if you want, though most teams pick one. Next.js 16 uses React Server Components. Every component is a server component by default. To make something interactive you mark it with `"use client"`: ```tsx // app/page.tsx import Hero from "./hero"; import Counter from "./counter"; import Newsletter from "./newsletter"; export default function Home() { return (

); } // app/counter.tsx "use client"; import { useState } from "react"; export default function Counter() { const [count, setCount] = useState(0); return ; } ``` The mental model is similar but the bundle outcome is different. In Next.js, the React runtime always ships. In Astro, if you have no interactive components, no JavaScript ships at all. ## Content: Where Astro Pulls Ahead Astro's Content Layer API is the killer feature for content-heavy sites. You define a collection with a Zod schema and a loader, and you get fully typed content access throughout your codebase. ```ts // src/content.config.ts import { defineCollection, z } from "astro:content"; import { glob } from "astro/loaders"; const blog = defineCollection({ loader: glob({ pattern: "**/*.md", base: "./src/content/blog" }), schema: z.object({ title: z.string(), date: z.coerce.date(), excerpt: z.string(), tags: z.array(z.string()), draft: z.boolean().default(false), }), }); export const collections = { blog }; ``` In a page you query the collection like a database: ```astro --- import { getCollection } from "astro:content"; const posts = (await getCollection("blog", ({ data }) => !data.draft)) .sort((a, b) => b.data.date.getTime() - a.data.date.getTime()); ---

{post.data.title} {post.data.date.toLocaleDateString()}

``` Next.js has no equivalent. You either roll your own markdown pipeline with `gray-matter` and `remark`, or you reach for Contentlayer (which is unmaintained), MDX with manual frontmatter parsing, or a headless CMS. None of these are as ergonomic as Astro's built-in story. ## Server Islands: Mostly Static, Partially Dynamic The historical pitch against Astro was: "what if I want a static page but with the user's logged-in name in the header?" The answer used to be "render the whole page on the server." Server Islands fixed this in Astro 5. ```astro --- // src/pages/index.astro import StaticHero from "../components/StaticHero.astro"; import UserMenu from "../components/UserMenu.astro"; ---

``` The page is statically generated and cached at the CDN. The `UserMenu` component is rendered on demand for each request and streamed in. The static shell loads instantly. The dynamic part fills in milliseconds later. This is conceptually the same thing Next.js 16 does with Partial Prerendering, but Astro applies it at the component level rather than the route level, which is usually what you want. ## Next.js: Where It Still Wins Next.js 16 dominates when the site is an application. A few cases where Astro is the wrong tool: **Authenticated dashboards.** Next.js middleware, server actions, and the React ecosystem (TanStack Query, Zustand, Jotai, shadcn/ui) make building a logged-in product surface dramatically faster. Astro can technically do all of this, but you will fight every step of the way. **Real-time UIs.** WebSocket-driven dashboards, collaborative editors, anything with persistent client state across navigations. Astro's MPA model means a full document reload on navigation, which destroys client state by default. View Transitions help, but persistent state is not the framework's core competence. **AI-native UIs.** The [Vercel AI SDK](/blog/vercel-ai-sdk-guide) and the streaming-first React ecosystem are tightly coupled to Next.js. If you are building a chat interface, an agent UI, or anything streaming tokens from a model, the rough edges in Astro are real. **Tight integration with the React Server Component model.** Server Actions, `revalidatePath`, `unstable_cache`, the cache directive - these are Next.js inventions. They are not coming to Astro. ## Decision Tree Ask three questions in order: 1. **Is the page authenticated and stateful?** If yes, Next.js 16. Stop here. 2. **Does the page need React-ecosystem libraries that depend on App Router primitives (Server Actions, RSC, streaming)?** If yes, Next.js 16. Stop here. 3. **Otherwise, Astro 5.** It will be faster, smaller, and cheaper to host. The fourth implicit question is which framework your AI coding tools work better with. In our [comparison matrix of every AI coding tool in 2026](/blog/ai-coding-tools-comparison-matrix-2026), Next.js has more training data and more idiomatic templates across [Claude Code](/tools/claude-code), Cursor, and Codex. Astro is well-supported but you will occasionally watch an agent invent a Next.js pattern that does not apply. If you live and die by AI assistance, weigh that. ## Hosting and Cost Astro deploys as static HTML to any CDN. Cloudflare Pages, Netlify, GitHub Pages, S3, anywhere. Server Islands run as edge functions but only for the components that need them, so the function invocation count stays low. A typical Astro marketing site [costs](/blog/ai-coding-tools-pricing-comparison) under a dollar a month at moderate traffic. Next.js 16 wants to deploy to Vercel. It runs elsewhere - Cloudflare Workers via OpenNext, AWS via SST, self-hosted via the standalone output - but each non-Vercel target has caveats. Function invocations multiply quickly because every dynamic route triggers a server invocation. The same traffic that costs a dollar on Astro can cost ten to fifty dollars on Next.js depending on the deployment target. ## Migration Patterns Most teams do not need to migrate. If your Next.js content site is working, leave it alone. If you are starting fresh, Astro is the better default for content. The migration that does make sense is splitting an existing site: - Keep `app.example.com` (the authenticated product) on Next.js 16. - Move `www.example.com` (marketing, blog, docs) to Astro 5. This is the pattern Vercel itself uses internally for some properties, and it gets you the best of both worlds without rewriting the application. A practical migration path with [Claude Code](/tools/claude-code): ```bash # Scaffold the new Astro site npm create astro@latest www -- --template blog --typescript strict # Have Claude Code port your existing pages claude -p "Port the marketing pages from ../next-app/app/(marketing) to Astro components in src/pages/. Preserve all SEO metadata. Use Astro Content collections for the blog." ``` The agent handles roughly 80 percent of a marketing-site port in a single session. You review, fix the edge cases, and ship. ## Watch the Deep Dive For a hands-on walkthrough showing both frameworks side by side, building the same marketing page in each: Subscribe to [Developers Digest on YouTube](https://www.youtube.com/@developersdigest) for new framework deep dives every week. ## The Honest Take Astro and Next.js are not competing for the same job in 2026. They look like they are because both render HTML, both use components, and both have a TypeScript story. But the underlying bet is different. Astro is betting that most websites are documents and should ship like documents. Next.js is betting that most websites are applications and should ship like applications. Both bets are correct, just for different sites. If you are honest about which kind of site you are building, the choice is obvious. The teams that struggle are the ones who pick a framework based on what is on the resume rather than what is on the page. If you want to keep going, [the Next.js AI app stack guide](/blog/nextjs-ai-app-stack-2026) covers the application side in depth, and [our framework comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) covers the broader landscape. ## Frequently Asked Questions ### Should I use Astro or Next.js for a blog in 2026? Astro. A blog is a content site, not an application. Astro's Content Layer API gives you typed markdown collections out of the box, pages ship with zero client JavaScript by default, and hosting costs are negligible. Next.js works for blogs but ships 85-250KB of JavaScript runtime that a static blog does not need. ### Is Next.js 16 faster than Astro 5? No. Astro 5 pages load faster because they ship less JavaScript. An empty Next.js 16 page ships 92KB of client JavaScript minimum. An empty Astro 5 page ships 0KB. However, Next.js is faster for client-side navigation after the initial load because the React runtime enables instant page transitions without full document reloads. ### Can Astro handle dynamic content and authentication? Yes, with caveats. Astro 5 Server Islands let you render specific components on demand while the rest of the page stays static. You can build authenticated pages, but Astro's multi-page architecture means you lose client state on navigation. For dashboards with persistent state, Next.js is the better tool. ### Does Astro work with React? Yes. Astro supports React, Vue, Svelte, Solid, and other UI frameworks as "islands." You can use shadcn/ui, Radix, or any React component library - they just only load JavaScript for the components you explicitly mark as interactive with `client:visible` or `client:load` directives. ### Why did Cloudflare acquire Astro? Cloudflare acquired Astro in early 2026 to strengthen its Pages and Workers platform. The acquisition means Astro has first-class Cloudflare deployment support, native edge runtime, zero cold starts on most routes, and tight integration with Cloudflare's CDN. Astro sites deploy anywhere, but Cloudflare is now the default recommendation. ### What is Partial Prerendering in Next.js 16? Partial Prerendering (PPR) lets a single Next.js route mix a static shell with streamed dynamic content. The static HTML caches at the CDN for instant first paint, then the dynamic parts fill in via streaming. It is conceptually similar to Astro's Server Islands but operates at the route level rather than the component level. ### How do AI coding tools compare between Astro and Next.js? Next.js has more training data across Claude Code, Cursor, and Codex because React and Next.js are more widely used. AI agents generate idiomatic Next.js code more reliably. Astro is well-supported but you may occasionally see an agent suggest a Next.js pattern that does not apply. If AI-assisted development is critical, weigh this in your decision. ### Can I migrate from Next.js to Astro? Yes, but the recommended pattern is to split rather than migrate entirely. Keep your authenticated application on Next.js and move your marketing pages, blog, and docs to Astro. This gets the performance benefits of Astro for content while keeping the React ecosystem for your application. Claude Code can automate roughly 80 percent of a marketing-site port in a single session.

Claude API Reliability: Error Handling Best Practices

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The reason your Claude app falls over Most production incidents I have seen with Claude integrations are not about the model. They are about the network between you and the model. For broader context, pair this with [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) and [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); those companion pieces show where this fits in the wider AI developer workflow. Rate limits. Timeouts. Transient 5xx. The occasional auth blip when an API key gets rotated and not propagated. None of these are interesting bugs. All of them will take your app down if you don't have the defensive layer in place. The good news: the defensive layer is small. Maybe 200 lines of code. Once it is in, your reliability story flips from "depends on whether [Anthropic](/blog/anthropic-vs-openai-developer-experience) had a good day" to "depends on whether you wrote your retry loop correctly," which is a much better problem to have. This post is the playbook. Error categorization, retry shape, rate limit handling, fallback strategy, and the monitoring you need to know any of it is working. ## The five error categories that matter Anthropic returns standard HTTP status codes plus a structured error body. The five buckets: **400 - bad request.** Invalid JSON, malformed message structure, schema violation on tool input. Permanent. Do not retry. Log the request body and fix the call site. The error message in the response body usually points directly at the problem. **401 - authentication.** API key is missing, wrong, or revoked. Permanent for this request. Do not retry. Alert immediately - this means your secrets pipeline is broken. **429 - rate limit.** Transient. Retry with exponential backoff. Anthropic returns a `retry-after` header on rate limit responses. Respect it. Don't guess. **500/502/503/504 - server errors.** Transient. Retry with backoff. The 504 specifically means a timeout on Anthropic's side, often during a slow generation. If it keeps happening on the same request, the prompt is too long or the `max_tokens` is too high. **Network errors.** ECONNRESET, ETIMEDOUT, DNS failures, TLS handshake failures. Transient. Retry with backoff. These are not from Anthropic, they are from the path between you and them. The Anthropic SDK exposes these as typed errors, which makes the dispatch clean. ```typescript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); function isRetryable(err: unknown): boolean { if (err instanceof Anthropic.APIError) { if (err.status === 429) return true; if (err.status && err.status >= 500) return true; return false; } if (err instanceof Anthropic.APIConnectionError) return true; if (err instanceof Anthropic.APIConnectionTimeoutError) return true; return false; } ``` Two errors not in the SDK type hierarchy that you still want to handle: bare `fetch` failures from a flaky network and JSON parse errors from a truncated response. Both are transient. Both want retries. ## Retry with exponential backoff and jitter The naive retry is "wait one second, try again, wait two, try again." This works for one client. With a hundred concurrent clients all retrying on the same wall-clock schedule, you get a thundering herd that takes the upstream down a second time the moment it recovers. The fix is jitter. Add random noise to the backoff so retries spread out instead of stacking. Full jitter (random between zero and the cap) is the safest variant. ```typescript async function sleep(ms: number) { return new Promise((r) => setTimeout(r, ms)); } function backoffMs(attempt: number, base = 500, cap = 30_000): number { const exp = Math.min(cap, base * 2 ** attempt); return Math.floor(Math.random() * exp); } async function withRetry( fn: () => Promise, options: { maxAttempts?: number; onRetry?: (attempt: number, err: unknown) => void } = {} ): Promise { const maxAttempts = options.maxAttempts ?? 5; let lastErr: unknown; for (let attempt = 0; attempt < maxAttempts; attempt++) { try { return await fn(); } catch (err) { lastErr = err; if (!isRetryable(err) || attempt === maxAttempts - 1) throw err; let delay = backoffMs(attempt); if (err instanceof Anthropic.APIError && err.status === 429) { const retryAfter = err.headers?.["retry-after"]; if (retryAfter) delay = Math.max(delay, Number(retryAfter) * 1000); } options.onRetry?.(attempt, err); await sleep(delay); } } throw lastErr; } const response = await withRetry(() => client.messages.create({ model: "claude-sonnet-4-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello" }], }) ); ``` A few things worth noting. The `retry-after` header takes precedence over the calculated backoff because Anthropic knows better than you do when to come back. The `onRetry` callback is where you push metrics - don't skip it. The max-attempts cap is at five because beyond that you are throwing good money after bad, and the human at the other end of your API has been waiting too long anyway. Note that the official Anthropic SDKs already do retry under the hood with sensible defaults. You can configure this with `maxRetries` on the client. The wrapper above is for the cases where you want explicit control - logging every retry, custom backoff shape, integration with a circuit breaker. ## Circuit breakers stop the bleeding When Anthropic is having a real outage (rare, but it happens), retrying is counterproductive. You burn budget on doomed requests and prevent your app from falling back to a degraded mode that might actually serve users. Circuit breakers solve this. Track recent failure rate. When it crosses a threshold, open the breaker - skip the upstream entirely and short-circuit to a fallback. Periodically try one request to see if upstream is back. Close the breaker when it recovers. ```typescript type BreakerState = "closed" | "open" | "half-open"; class CircuitBreaker { private state: BreakerState = "closed"; private failures = 0; private openedAt = 0; constructor( private threshold = 5, private resetMs = 30_000 ) {} async run(fn: () => Promise): Promise { if (this.state === "open") { if (Date.now() - this.openedAt > this.resetMs) this.state = "half-open"; else throw new Error("circuit open"); } try { const result = await fn(); if (this.state === "half-open") { this.state = "closed"; this.failures = 0; } return result; } catch (err) { this.failures++; if (this.failures >= this.threshold) { this.state = "open"; this.openedAt = Date.now(); } throw err; } } } const breaker = new CircuitBreaker(); async function callClaude(input: string) { return breaker.run(() => withRetry(() => client.messages.create({ model: "claude-sonnet-4-5", max_tokens: 1024, messages: [{ role: "user", content: input }], }) ) ); } ``` Tune the threshold to your traffic. For an app doing 1000 RPM, a threshold of 5 fires too eagerly on a normal 1 percent failure rate. For an app doing 10 RPM, a threshold of 50 takes 5 minutes to detect a real outage. A rolling-window failure rate (e.g. open if 50 percent of the last 20 requests failed) is more robust than absolute counts. ## Rate limits: prevent before retry Retrying 429s is fine. Not hitting them is better. Anthropic rate limits are organization-wide and measured in input tokens per minute, output tokens per minute, and requests per minute. The exact numbers depend on your usage tier. The mistake teams make is assuming the rate limit applies per-key or per-host - it does not. Three patterns to stay under the limit. **Token bucket on your side.** Estimate the input + output tokens for each call. Refill the bucket at your tier's rate. Block (or queue) when the bucket is empty. This is the single best rate limit prevention pattern. **Spread bursts.** If you have 100 agent runs to launch, don't fire them all at once. Stagger over 60 seconds. Same total throughput, none of the burst pain. **Watch the headers.** Anthropic returns `anthropic-ratelimit-requests-remaining` and similar headers on every response. When `remaining` drops below 10 percent of your limit, slow down. The headers are the only honest source of truth. ```typescript class TokenBucket { private tokens: number; private lastRefill = Date.now(); constructor(private capacity: number, private refillPerMs: number) { this.tokens = capacity; } async take(amount: number): Promise { while (true) { this.refill(); if (this.tokens >= amount) { this.tokens -= amount; return; } const needed = amount - this.tokens; const waitMs = Math.ceil(needed / this.refillPerMs); await sleep(waitMs); } } private refill() { const now = Date.now(); const delta = (now - this.lastRefill) * this.refillPerMs; this.tokens = Math.min(this.capacity, this.tokens + delta); this.lastRefill = now; } } ``` ## Timeouts: pick a number and enforce it Default SDK timeout is 10 minutes. That is too long for almost every production use case. Pick a real number based on your UX budget. Interactive chat: 30 seconds total, but stream so the user sees tokens at 1s. If generation hasn't finished by 30s, cancel. Agent step: 60-90 seconds. Long enough for a slow tool result to come back. Short enough that a stuck agent doesn't burn budget for an hour. Batch job: whatever your batch SLA allows, but always finite. ```typescript const response = await client.messages.create( { model: "claude-sonnet-4-5", max_tokens: 1024, messages: [{ role: "user", content: "Hello" }], }, { timeout: 30_000 } ); ``` For streaming requests, time-to-first-token and total-time are different timeouts. Time-to-first-token should be 5-10s. Total time depends on how long an answer you want. ## Fallback strategies When Claude is down or slow or rate-limited and you cannot wait, the question is what to do instead. Options in increasing order of "effort to set up": **Cached response.** If the same question was asked recently, return the prior answer with a "cached" badge. Free, fast, sometimes wrong. **A smaller model.** Fall back from Sonnet to Haiku. Lower quality, much higher availability headroom, lower cost. For a lot of use cases the user won't notice. **A different provider.** Have a parallel path through OpenAI or Google. Triggered only when the breaker is open. Be honest with yourself about what fraction of your prompts are portable - tool use schemas, [prompt caching](/blog/prompt-caching-claude-api-production-guide), and extended thinking will not transfer cleanly. **A static degraded UX.** Show "AI is temporarily unavailable, here are some prewritten resources." Last resort. Better than a blank page. The right choice depends on the business cost of latency versus the business cost of a wrong answer. For a customer support chatbot, cached or smaller-model is usually better. For a financial advisor, static degraded is better. ## Observability: you can't fix what you can't see The reliability work above does nothing if you don't know when it fires. Five metrics, every Claude call. Latency p50, p95, p99. Error rate by status code. Tokens in, tokens out, cost per call. Cache hit rate (if you are using prompt caching). Retry count distribution. Log structured. Every call gets request_id, status, latency, tokens, retries, model. The Anthropic response headers give you a request ID that is what their support team will ask for if you file a ticket. Save it. We run all of this on [agent-finops](/projects) for cost and rate-limit visibility, and replay the actual prompt/response pairs through [tracetrail](/projects) when something looks weird. The combination is the difference between "we had an incident yesterday" and "we know exactly what happened, here is the fix." If you want to see the full reliability stack assembled in a working app, the [DevDigest YouTube channel](https://www.youtube.com/@DevelopersDigest) walks through the wrapper, the breaker, and the dashboards on a real service. The patterns are not exotic. The discipline of actually shipping them is what separates the apps that stay up from the ones that don't. Reliability is not a feature you add at the end. It is the layer underneath every Claude call from request one. Build it once, build it right, and the model failures stop being your problem.

Claude Batch API: Cutting Async Workload Costs In Half

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## A 50% Discount Hiding In Plain Sight If you have a Claude workload that doesn't need to answer in real time, you are probably overpaying by 2x. The Batch API charges half - half - the per-token rate of the synchronous API in exchange for results within 24 hours. For nightly reports, content classification, synthetic data generation, document analysis, and most agent evaluations, that trade is a no-brainer. And yet most teams I look at still run those workloads through the live API because nobody wants to refactor the request loop. This is the version of the docs I wish I had the first time I moved a real workload to batch. We will cover the request format, the SDK code you should ship, the architecture changes async forces on your stack, and the failure modes you only learn about after a 100k-request batch silently drops 4% of its results. We walked through a real migration in our [Batch Processing for Scale: 100k Requests/Day](https://www.youtube.com/@developersdigest) video on YouTube. This post is the production-grade companion. ## When Batch Wins, And When It Loses Batch is the right answer when: - The user doesn't see the result immediately. Reports, classification jobs, ETL pipelines, eval suites. - You can tolerate up to a 24-hour SLA. Most batches finish in well under an hour, but you should not promise less than 24h to your callers. - Volume is non-trivial. Below ~1000 requests per batch, the operational overhead of async eats the cost win. - The cost per request matters. At 5 cents a call, 50% off is a real number; at 0.05 cents a call, the engineering cost dwarfs the savings. Batch is the wrong answer when: - A user is waiting on the response. Latency is unbounded. - The workload is spiky and unpredictable. Batches benefit from steady throughput. - Each request depends on the last. Conversations, agent loops, and anything stateful belong on the synchronous API. The hybrid pattern - synchronous for user-facing work, batch for everything else - is what mature deployments look like. Customer-asked-a-question goes live; nightly data labeling goes batch. ## What Batch Actually Is, Mechanically You package up to 100,000 message-create requests into a single request file. You submit it. [Anthropic](/blog/anthropic-vs-openai-developer-experience) processes them in parallel on a separate, lower-priority infrastructure. You poll for completion or subscribe to a webhook. When done, you download a results file and match results back to your inputs by `custom_id`. Three properties to internalize: 1. **Each row is an independent message-create call.** You get the full request body - model, messages, tools, system, thinking, cache_control, everything. Batch is "synchronous API at half price with a delayed return," not a different API. 2. **Order is not preserved.** Results come back in whatever order they finished. You match on `custom_id`. Anyone who ignores this and zips inputs to outputs gets bitten. 3. **Failures are per-request, not per-batch.** Individual rows can fail (rate limit on a tool call, validation error, anything) without taking the batch down. You must scan the result file for errors. ## The TypeScript Code You Should Actually Ship Here is a minimal but production-shaped batch submission using the official Anthropic SDK. It builds requests with stable IDs, submits, polls, and reconciles results. ```typescript import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); type ClassifyInput = { id: string; text: string }; const SYSTEM = "Classify the input as one of: bug, feature, question, spam. Return only the label."; function buildRequests(inputs: ClassifyInput[]) { return inputs.map((input) => ({ custom_id: input.id, params: { model: "claude-haiku-4-5" as const, max_tokens: 16, system: SYSTEM, messages: [{ role: "user" as const, content: input.text }], }, })); } export async function classifyBatch(inputs: ClassifyInput[]) { const batch = await client.messages.batches.create({ requests: buildRequests(inputs), }); let status = batch; while (status.processing_status !== "ended") { await new Promise((r) => setTimeout(r, 30_000)); status = await client.messages.batches.retrieve(batch.id); } const results: Record = {}; for await (const result of await client.messages.batches.results(batch.id)) { if (result.result.type === "succeeded") { const block = result.result.message.content[0]; results[result.custom_id] = block.type === "text" ? block.text.trim() : ""; } else { results[result.custom_id] = `__error__:${result.result.type}`; } } return results; } ``` A few non-obvious things this captures: - `custom_id` is yours to define and must be unique per batch. We use whatever primary key the input row has in our database. This is how you reconcile results to records. - The SDK's `results()` iterator streams a JSONL file. Do not try to load it into memory for large batches; iterate. - The polling loop here is naive. In production, use a webhook or a worker that wakes on schedule. A 30-second poll is fine for prototyping; do not run it for thousands of batches in parallel. ## Webhooks Beat Polling Every Time Polling at scale is a trap. Each batch runs for an unknown duration, and a fleet of polling workers either churns CPU or sleeps too long. Webhooks are the right pattern. Configure a webhook endpoint in your Anthropic console or via API, and Anthropic will POST a notification when a batch finishes. Your handler: 1. Verifies the signature 2. Pulls the results file via the SDK 3. Iterates and writes to your database 4. Marks the job as complete Two operational notes from production: webhooks can fire more than once (idempotent handlers, please), and the events occasionally arrive out of order with the batch's own status field. Trust the batch's status when you fetch it, not the event payload alone. ## Reconciliation: The Single Most Important Step The bug you don't notice in dev and absolutely will hit in prod: a 99,500-row result file for a 100,000-row batch, and you ship the answer assuming all rows came back. The reconciliation pattern that survives: ```typescript async function reconcile(batchId: string, expectedIds: Set) { const seen = new Set(); const errors: { id: string; reason: string }[] = []; const ok: { id: string; output: string }[] = []; for await (const r of await client.messages.batches.results(batchId)) { seen.add(r.custom_id); if (r.result.type === "succeeded") { const block = r.result.message.content[0]; ok.push({ id: r.custom_id, output: block.type === "text" ? block.text : "" }); } else { errors.push({ id: r.custom_id, reason: r.result.type }); } } const missing = [...expectedIds].filter((id) => !seen.has(id)); return { ok, errors, missing }; } ``` You always end up with three buckets: succeeded, errored, and missing. Each bucket needs a path. Errored rows are eligible for retry on the live API or a follow-up batch. Missing rows are the silent failure mode and almost always indicate a bug in how you constructed the batch (duplicate custom_ids, oversized rows, encoding problems). ## Cost Modeling: Where The 50% Actually Lands The 50% discount applies to both input and output tokens. Cache reads, cache writes, thinking tokens - all 50% off in batch mode. There is no separate "batch tier" to opt into beyond using the batch endpoint. The savings stack with caching. A nightly classification batch of 100k rows with a 4k-token shared instruction: - Sync: 100k x 4000 input tokens + 100k x 50 output, about $1,275 at Haiku rates - Sync + caching: instruction cached once per 5 min, about $200 if calls are bursty - Batch + caching: about $100 For workloads with stable instructions and high request counts, batch + cache is the cheapest configuration available on the Claude API today. For monitoring batch spend over time and catching regressions, [CodeBurn](/blog/codeburn-tui-dashboard-for-claude-code-token-spend) tracks per-batch tokens and per-job cost so you can spot the runaway batch before the invoice shows up. ## Real-World Batch Workloads **1. Daily content classification.** Tag a few hundred thousand rows of incoming user content with categories. Haiku in batch mode runs about $1 per 100k rows for short text. We have shipped this on three different products. **2. Scheduled report generation.** Generate per-customer summaries overnight. The latency floor is fine because the report lands in the inbox at 7am anyway. Sonnet in batch mode is the right model. **3. Synthetic data generation.** Generating eval datasets, training sets, or persona-conditioned variants. These are big, embarrassingly parallel, and not user-facing. Perfect batch fit. **4. Eval suites.** Running a 10k-prompt eval against five models takes 50,000 calls. Batch all of them, reconcile, compute metrics. Cuts both cost and wall-clock time vs. naive serial calling. **5. Document re-indexing.** Re-summarizing or re-extracting from a corpus when you change your prompt. Every team I know that runs [RAG](/blog/what-is-rag) eventually has a "rebuild all summaries" job; this is what batch is for. ## Production Gotchas Worth Pinning To Your Wall **1. Per-batch row limits.** Up to 100,000 requests or 256MB total, whichever hits first. For larger jobs, shard into multiple batches. A simple sharding scheme: hash custom_id mod N. **2. Rate limits still apply.** Batches share quota with synchronous calls in a way that surprised us the first time. A huge batch can cause your synchronous calls to hit `overloaded_error`. If your live traffic shares the API key with batch, watch the interaction. **3. Cache reads work, cache writes do not propagate to live calls.** A cache write inside a batch creates an entry usable by other batch and live calls - but the timing means you generally get cache writes per-row, not benefit from cache reads. Cache the prefix shared across all rows by ensuring the first row in the batch creates the cache, and letting subsequent rows read it. In practice the SDK handles this automatically when `cache_control` is set on shared prefix blocks. **4. Tool use works, but is rarely useful in batch.** Batch is for one-shot calls. If a row requires a tool result, you cannot loop within the batch - you would need to take the tool calls out, run them yourself, and submit a follow-up batch. Most batch workloads should not use tools at all. **5. The 24-hour SLA is a ceiling, not a target.** Median completion in our measurements is 5 to 30 minutes. Plan for 24h, but don't design dashboards that show "still processing" for the first 12 hours and panic users. **6. Batch IDs are forever in your DB.** You will want to query by batch ID six months later when an auditor asks where row 47,318 of a March classification job went. Store batch IDs alongside the records they generated, not in a side table that gets pruned. ## Hybrid Architecture: The Endgame The pattern mature production stacks land on: ``` [user request] |- if interactive -> [synchronous API w/ caching] |- if backgroundable -> [enqueue] |- [batch worker pulls every N min] |- [submits batch] |- [webhook -> reconcile -> notify] ``` The interesting decision is the boundary. We move workloads to batch the moment we can answer "is anyone watching the spinner" with "no." Reports, daily syncs, classification, evals, summaries, embeddings (when we still need them). Anything user-facing stays synchronous, often on Haiku, often with thinking off. The [400-Dollar Overnight Bill](/blog/400-dollar-overnight-bill-agent-finops) post-mortem walks through what happens when this boundary blurs and a "should be batchable" job ends up on the live API at full price. ## Production Checklist Before You Ship - [ ] `custom_id` set to your stable record ID, unique per batch - [ ] Reconciliation step that produces succeeded / errored / missing buckets - [ ] Webhook endpoint configured and signature-verifying - [ ] Idempotent handler for duplicate webhook deliveries - [ ] Batch ID stored alongside generated records - [ ] Per-batch token cost logged and alertable - [ ] Sharding strategy for jobs over 100k rows - [ ] Retry strategy for errored rows (live API or follow-up batch) - [ ] Monitoring on batch completion latency, alert on stragglers > 12h - [ ] Documented latency SLA to upstream callers (24h, not 1h) The Batch API is the cheapest legitimate cost lever on the Claude platform after prompt caching. The tax is a real architecture change to async, and you should not pretend otherwise. But for teams running any kind of bulk classification, generation, or analysis, it is straightforwardly half the bill for the same answers. For more on optimizing Claude in production, see our writeups on [prompt caching](/blog/prompt-caching-claude-api-production-guide) and [tool use patterns](/blog/tool-use-claude-api-production-patterns).

Claude Design: Anthropic's Bet That Designers and Developers Want the Same Tool

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

[Anthropic](/blog/anthropic-vs-openai-developer-experience) shipped Claude Design and the framing is unusual. It is not a Figma clone, not a v0 competitor, and not a wrapper around a chat box that emits Tailwind. It is a design surface that reads your repo, builds a style guide from what is actually in the codebase, and then generates UI that respects it. For developers who have been hand-rolling DESIGN.md files and pasting screenshots into Claude Code for the last six months, this is the productized version of that workflow. I spent a session with it for the [Claude Design in 12 Minutes](https://www.youtube.com/watch?v=kpfxNOhw0nk) video and the short version is: this is the first AI design tool that feels like it was built by people who watch developers work, not by people who watch designers work. ## What Claude Design actually is Claude Design is a hosted product from Anthropic that combines three things most teams currently glue together by hand. 1. A design system extractor. Point it at a Git repo or a Figma file and it scans the existing UI, pulls out colors, typography, spacing, components, and writes them into a structured file system that the model uses as context for everything that comes next. 2. A high-fidelity generation surface. Prompts produce real, editable layouts with multiple variants. Pricing pages, hero sections, slide decks, prototypes, dashboards. 3. A handoff layer. Export to Canva, PDF, PowerPoint, or, more interestingly for us, raw HTML and CSS that drops straight into a coding agent like [Claude Code](/blog/what-is-claude-code-complete-guide-2026) or Cursor. The model under the hood is Opus 4.7, which Anthropic has tuned for higher-resolution visual reasoning. That matters more than the marketing makes it sound. The tool can take a screenshot of its own output, evaluate it, and iterate. The QA loop is built in. ## The repo scan is the unlock Most AI design tools start from zero. You type "build me a SaaS landing page" and you get the median aesthetic of the internet: blue-to-purple gradient, rounded cards, Lucide icons, three-column features grid. We covered that failure mode in [AI design slop and how to spot it](/blog/ai-design-slop-and-how-to-spot-it). Claude Design starts from your code. When I pointed it at the Developers Digest site repo, it produced a style guide that matched the actual product within about ninety seconds. Cream background, ink type, the pink accent, the offset card pattern, Geist font stack, no gradients. None of that came from a prompt. It came from reading the Tailwind config, the components directory, and the rendered pages. The output is a structured set of files the model uses as context for every subsequent generation. You can edit them directly. You can also commit them. ```bash # After the repo scan, the design system lands as editable files design-system/ tokens.json # colors, type scale, spacing, radii components/ button.html # canonical button variants card.html nav.html guidelines.md # voice, layout rules, do/don't list ``` This is the same shape as the [DESIGN.md pattern](/blog/design-md-for-ai-agents) that has been spreading through the Claude Code ecosystem, except generated and maintained for you. The Developers Digest version also has a [design-system reference](/design-system) so the written contract and shipped UI stay connected. ## The one-shot pricing page The headline demo is generating a [pricing](/blog/ai-coding-tools-pricing-2026) page in one shot. I have done this exercise enough times in raw Claude Code to be skeptical. The result was good enough that I shipped a variant of it. Three layout options came back: a standard three-tier card grid, a comparison table with feature rows, and a single-tier focus layout for a one-product pitch. Each one used the actual product palette. Each one had editable "tweaks" exposed as inline controls, the same kind of UI dial you get in Figma when you adjust a component property, except the underlying mutation is a model call. The screenshot-based edits are where it stops feeling like a chat interface. You drop a screenshot in, point at a region, and ask for a change. The model resolves the pointed-at element to a DOM node and edits the underlying markup. Voice input works the same way. "Make this section more compact and move the testimonials above the FAQ" with a circle drawn around the section produces the right diff. ## Where this slots in for developers I do not think Claude Design is going to replace your [coding agent](/blog/what-is-an-ai-coding-agent-2026). I think it slots in front of it, in the place where most teams are currently flailing. The handoff is the proof. Generate the design in Claude Design. Export the HTML and CSS. Drop the assets into your repo. Hand the files to Claude Code with a prompt like "convert this static export into a working [Next.js](/blog/nextjs-ai-app-stack-2026) page using our existing components and routing." That last step is where coding agents earn their keep, and the design tool stops being a wrapper. Here is the rough loop I have been running. ```bash # 1. Generate in Claude Design, export to /tmp mv ~/Downloads/claude-design-export.zip /tmp/cd-export.zip unzip /tmp/cd-export.zip -d /tmp/cd-export # 2. Hand off to Claude Code in the project repo claude -p "Take the static HTML in /tmp/cd-export and rebuild it as a \ Next.js page at app/pricing/page.tsx using our existing components in \ @/components/ui. Match the styling but use our Tailwind tokens, not \ inline styles." ``` The split makes sense. Claude Design owns the visual decisions and the iteration loop. Claude Code owns the integration into your actual codebase. Neither one is good at the other half. ## The 3D banner moment The demo that got the loudest reaction in the comments was the 3D hero banner with parallax. A single prompt, ten seconds of streaming, and a layered scene came out with depth, motion on scroll, and a real sense of composition. It is not production-ready in every case, but it is the first time I have seen a prompt-to-hero flow where the result did not need a complete rewrite. The streaming UI matters here too. You watch the design assemble in real time. When something is going wrong, you cancel before the full generation completes. That is a small UX detail that turns into a real time saver across a session. ## What is missing A few honest gaps. It is not local. Everything runs in Anthropic's cloud, which means private repos go through their pipeline. For most teams that is fine, for some it is a non-starter. The same caveat applies to anything in the [Claude Managed Agents](/blog/anthropic-cowork) line. The export is HTML and CSS, not React or Vue. You get clean markup, but you still bring your own framework adapter. This is probably correct, since the alternative is a tool that generates broken Next.js components and tries to look smart about it. There is no real version control inside the product yet. You can save designs, but the diff between version A and version B is not first class. For a product whose entire pitch is iteration, that is the next obvious feature. ## Why the bigger picture matters Anthropic is doing something specific with this launch and the [Claude Skills marketplace](/blog/claude-code-skills-marketplace-launch) and Co-work. They are building a layer above the model where the work product is structured artifacts, not chat transcripts. Design files. Style guides. Skills. Sub-agents. The model is becoming the smallest unit, and the company is shipping the surfaces around it. For developer tools, this matters because the moat in 2026 is not the model. The moat is the structured context you keep around the model. A design system that lives in your repo and gets read every time you generate UI is moat. A skill that turns three thousand tokens of instructions into a reusable behavior is moat. A coding agent that knows your codebase is moat. Claude Design is the first time I have seen Anthropic ship a product where the structured artifact, not the chat window, is the primary UI. ## Quick start for developers If you want to try it without committing a project repo, here is the path of least resistance. 1. Start a throwaway repo with the look you want to match. A landing page with your brand colors, type, and three or four real components is enough. 2. Push it to GitHub, point Claude Design at it, let it scan. 3. Generate one page. Inspect the style guide it created. Edit anything wrong by hand. 4. Generate a second page using the same system. Confirm the consistency holds. 5. Export, hand off to Claude Code, ship. That loop took me about forty minutes the first time and about ten minutes the second time. The cost is mostly cognitive, not financial. Anthropic has not published per-design pricing yet, and inside the Max plan it appears to count against the same usage budget as everything else. We covered the broader [Claude usage limits playbook](/blog/claude-code-usage-limits-playbook-2026) recently, the same caveats apply. ## Bottom line Claude Design is not the most flashy thing Anthropic shipped this quarter. The Skills marketplace and Co-work probably matter more for the long arc. But Claude Design is the cleanest single-product example of where AI tooling is heading: read the user's existing artifacts, generate new artifacts that fit, hand off cleanly to the next tool in the chain. For developers who already have a [Claude Code workflow](/blog/ai-native-development-workflow), this is the missing piece in front of it. Try the repo scan, ship one page through the full loop, decide for yourself. Watch the full walkthrough on the [Developers Digest YouTube channel](https://www.youtube.com/@developersdigest) and let me know in the comments which part of the workflow you want to see broken down further.

Claude Opus 4.7: The Developer's Guide to Anthropic's New Flagship

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

[Anthropic](/blog/anthropic-vs-openai-developer-experience) shipped Claude Opus 4.7 today, and it is the most consequential Opus release since 4.5 first crossed the agentic threshold. The headline is not raw IQ. It is endurance. Opus 4.7 stays coherent across longer agent runs, takes better tool calls per dollar, and does it on a pricing curve that finally lets teams put Opus inside the hot path. This is the developer's guide. What changed under the hood, what to migrate, what to leave on Sonnet, and the production patterns that actually pay off. ## What's New in Opus 4.7 Anthropic's release notes lean on three numbers, and all three matter for builders. The first is SWE-bench Verified. Opus 4.7 lands at 81.4 percent on the hard end-to-end coding benchmark, up from 79.1 on Opus 4.6 and well clear of GPT-5.3's 76.8. That is not a rounding error. On real repos with real test suites, the model finishes more tasks without a human re-prompt. The second is Terminal-bench. This is the harness that grades a model on shell-driven tasks: file edits, git, build commands, log triage. Opus 4.7 hits 64.2 percent, a seven-point jump over 4.6. If your agent runs in a sandbox, this is the number that maps to your daily reality. The third is the long-horizon agent score. Anthropic now publishes a 30-step task completion rate. Opus 4.7 holds 71 percent across 30 sequential tool calls without losing the plot. Opus 4.6 was at 58. That is the difference between an agent that needs babysitting and one that finishes the ticket. Other shipped changes worth noting: - 1M token context is now generally available on the standard tier, not behind a flag - Native parallel tool calls are stable, with up to 16 concurrent calls per turn - Vision quality on diagrams, whiteboards, and UI screenshots is materially better - New `cache_control` ergonomics that let you mark blocks as ephemeral or persistent - Reduced refusal rate on legitimate security and red-team work ## Pricing Snapshot Opus has historically been the model you reach for and then nervously stare at the dashboard. 4.7 changes the math. - Input: $11 per million tokens (down from $15) - Output: $55 per million tokens (down from $75) - Cached read: $1.10 per million tokens - Cached write: $13.75 per million tokens - Batch API: 50 percent off both directions A 200K-token system prompt that used to cost $3 per request now [costs](/blog/ai-coding-tools-pricing-comparison) $0.22 on a cache hit. That is a 14x reduction on the dominant cost in most agent workloads. If you have an Opus app you shelved on cost grounds last year, run the numbers again. ## The SDK in Practice Here is the minimum viable Opus 4.7 call with the official Anthropic SDK. The model id is `claude-opus-4-7`. ```ts import Anthropic from "@anthropic-ai/sdk"; const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 4096, system: [ { type: "text", text: "You are a senior backend engineer reviewing pull requests.", cache_control: { type: "ephemeral" }, }, ], messages: [ { role: "user", content: "Review the diff in the attached patch and flag any concurrency bugs.", }, ], }); console.log(response.content); ``` Two things to notice. The system block is wrapped as a typed array so we can attach `cache_control`. And we are not setting `temperature` because Opus 4.7 ships with sane defaults for code review work. For agent loops, parallel [tool use](/blog/tool-use-claude-api-production-patterns) is where 4.7 shines. The model now plans tool calls in batches without the prompt gymnastics earlier versions needed. ```ts const tools = [ { name: "read_file", description: "Read a file from the repo.", input_schema: { type: "object", properties: { path: { type: "string" } }, required: ["path"], }, }, { name: "run_tests", description: "Run the test suite for a given package.", input_schema: { type: "object", properties: { pkg: { type: "string" } }, required: ["pkg"], }, }, ]; const turn = await client.messages.create({ model: "claude-opus-4-7", max_tokens: 8192, tools, tool_choice: { type: "auto", disable_parallel_tool_use: false }, messages: history, }); ``` Set `disable_parallel_tool_use` to `false` and Opus 4.7 will read three files and kick off two test runs in a single assistant turn. On a 20-step agent loop, that compresses wall time roughly 40 percent in our internal builds. ## Prompt Caching, Done Right Cache hit rate is the single biggest knob between an Opus app that loses money and one that prints it. The pattern that keeps paying off: 1. Put the largest stable content first. System prompt, tool definitions, retrieved docs. 2. Mark the last stable block with `cache_control: { type: "ephemeral" }`. 3. Append per-request user content after the cache marker. 4. Keep request structure byte-stable. Even reordering JSON keys can bust the cache. A real example. We shipped an internal code review agent on Opus 4.7 last week. The system prompt is 180K tokens of repo context, conventions, and a 20-tool definition block. Without caching, every PR review cost about $2.40. With ephemeral caching across a single review session, the second turn onward drops to $0.18. Across 1,000 reviews per week that is the difference between a $9.6K bill and a $720 bill. For a deeper walkthrough on the agent side of this, see our [Claude Opus 4.6 deep dive](/blog/claude-opus-4-6) and our [agent memory patterns guide](/blog/ai-agent-memory-patterns). ## When to Use Opus 4.7 vs Sonnet vs Haiku The temptation with every Opus release is to default-route everything to it. Resist. **Reach for Opus 4.7 when:** - The task spans more than 10 tool calls without a clear handoff - The output has to be correct on the first pass (migrations, security work, financial logic) - The context exceeds 300K tokens and you need real recall, not just a window - You are debugging the kind of bug where a wrong fix makes the problem worse **Stay on Sonnet 4.6 when:** - Latency matters and the task is bounded (chat replies, single-file edits, classification) - Volume is high and the task is well-structured - You can verify outputs cheaply **Use Haiku 4.5 when:** - You are running a router, classifier, or extractor - The work is parallelizable across thousands of items - A wrong answer is recoverable A practical pattern we use across the [Developers Digest portfolio](https://developersdigest.tech): Haiku for first-pass triage, Sonnet for the working layer, Opus 4.7 reserved for the synthesis and review steps. That keeps cost predictable and quality high. ## Production Patterns That Actually Ship A few patterns that have earned their keep on real Opus 4.7 deployments: **Compaction over conversation length.** Once a conversation crosses about 400K tokens, even Opus starts to drift on the earliest content. Periodically compact the transcript into a structured summary and replay it as the new system prompt. The 1M window is a safety net, not a working surface. **Explicit tool budgets.** Tell the model how many tool calls it has. "You have a budget of 8 tool calls. Plan accordingly." Opus 4.7 respects budgets in a way 4.5 never did. **Verifier-in-the-loop.** For anything that touches production, run the Opus output through a Sonnet verifier with the question "is this safe to apply." Sonnet is faster and cheaper, and disagreements between the two are a strong signal something is off. **Cache the world.** If a block of context is reused even three times in a session, mark it ephemeral. The break-even on cache writes is now under 2 reuses given the new [pricing](/blog/ai-coding-tools-pricing-2026). For the full agentic stack we recommend on top of Opus 4.7, see our [agentic dev stack guide](/blog/agentic-dev-stack-2026), and try [SubAgent](https://subagent.developersdigest.tech) for managing parallel agent fleets, [AgentHub](https://agenthub.developersdigest.tech) for orchestration, and the [DD CLI](https://cli.developersdigest.tech) for stitching it all into your terminal workflow. ## Real-World Benchmarks We Ran Synthetic benchmarks tell part of the story. We ran Opus 4.7 against three internal workloads we use every week, and the deltas are worth sharing. **Workload 1: Multi-repo refactor.** We took a known-painful refactor across 14 packages in a TypeScript monorepo. The task: rename a deeply-coupled service interface and update every call site, including tests. Opus 4.6 finished in 23 tool turns with two compile errors left over. Opus 4.7 finished in 16 turns with zero compile errors. Wall time dropped from 14 minutes to 8. **Workload 2: Production log triage.** Given 12K lines of structured logs and a vague bug report, find the root cause and propose a patch. Opus 4.6 surfaced the right area but missed the actual race condition in 3 of 10 runs. Opus 4.7 nailed the race condition 9 of 10 times and proposed a patch that compiled in 8 of those. **Workload 3: Long-form technical writing.** Drafting a 4K-word migration guide from a code diff plus three reference docs. Quality is subjective here, but we A/B'd internally and 4.7 won 7 of 10 blind reads from senior engineers. The complaint pattern shifted from "this is wrong" to "this is too long," which is a good problem to have. The signal across all three: 4.7 is not just smarter, it is more consistent. Variance across runs dropped noticeably, which matters more than peak score for any system you put on a schedule. ## Streaming, Thinking, and Vision A few more SDK details worth knowing if you are deploying 4.7 today. Streaming with extended thinking is now a first-class flow. The thinking blocks come through the stream as a distinct event type, so you can render a "thinking" UI without parsing prose. For chat surfaces this matters because users tolerate a 12-second response if they can see the model working. Vision quality stepped up. Hand-drawn whiteboards, architecture diagrams, and dense product screenshots all transcribe better. We use this for an internal tool that turns Figma exports into route stubs, and the false-route rate dropped from 18 percent to 6 percent on the same fixture set. Citations are stable on long-document workloads. If you build RAG, the response now reliably points at the source span without prompt-engineering acrobatics. ## Migration Notes from 4.6 If you are upgrading from Opus 4.6, the changes are mostly drop-in: - Swap the model id from `claude-opus-4-6` to `claude-opus-4-7` - Re-tune `max_tokens` upward by about 20 percent. Opus 4.7 plans more verbosely - Reduce your retry counts. 4.7 fails less often on tool schemas - Audit any prompt that says "do not use parallel tool calls". That guardrail is no longer needed - If you used `extended-thinking` on 4.6, the same flag works on 4.7 with a wider thinking budget The one breaking change to watch: tool result blocks now require explicit `is_error: true` for failure cases if you want the model to retry. 4.6 inferred this. 4.7 wants you to be explicit. ## A Builder's Take Opus 4.7 feels like the first Opus release where the price-to-capability curve actually invites production use across the full app surface. 4.5 was the agentic breakthrough. 4.6 made it serious. 4.7 makes it economical. The interesting second-order effect is that the gap between Opus and Sonnet is narrowing on price faster than it is on capability. That changes the routing math in any agent system. You can now afford Opus on the steps that used to fall back to Sonnet for cost reasons, and the quality lift is meaningful. If you build agents, ship a 4.7 migration this week. If you build apps, run the numbers on whether the Opus tier becomes your default. If you build internal tools, the 1M context plus aggressive caching is genuinely new product surface. Watch the full breakdown on the [Developers Digest YouTube channel](https://www.youtube.com/@DevelopersDigest?sub_confirmation=1) and subscribe for the next model drop. The cycle is not slowing down. ## Frequently Asked Questions ### What is Claude Opus 4.7 and how is it different from 4.6? Opus 4.7 is Anthropic's latest flagship model, released April 2026. The key improvements over 4.6 are: SWE-bench Verified score of 81.4% (up from 79.1%), Terminal-bench at 64.2% (up 7 points), and a 30-step agent completion rate of 71% (up from 58%). The model holds coherence across longer agent runs and costs significantly less - input dropped from $15 to $11 per million tokens, output from $75 to $55. ### How much does Claude Opus 4.7 cost? Input costs $11 per million tokens. Output costs $55 per million tokens. Cached reads are $1.10 per million tokens, and cached writes are $13.75 per million tokens. The Batch API gets 50% off both directions. A 200K-token system prompt that cost $3 on 4.6 now costs $0.22 on a cache hit. ### When should I use Opus 4.7 versus Sonnet 4.6? Use Opus 4.7 for tasks spanning more than 10 tool calls, work that must be correct on the first pass (migrations, security, financial logic), contexts exceeding 300K tokens, or debugging where a wrong fix makes things worse. Stay on Sonnet 4.6 when latency matters, volume is high, or outputs are easily verifiable. ### How do I migrate from Claude Opus 4.6 to 4.7? Swap the model id from `claude-opus-4-6` to `claude-opus-4-7`. Increase `max_tokens` by about 20% since 4.7 plans more verbosely. Reduce retry counts since 4.7 fails less on tool schemas. Remove any "do not use parallel tool calls" guardrails. One breaking change: tool result blocks now require explicit `is_error: true` for failures - 4.6 inferred this, 4.7 requires it. ### How do I enable prompt caching with Opus 4.7? Put your largest stable content first (system prompt, tool definitions, retrieved docs). Mark the last stable block with `cache_control: { type: "ephemeral" }`. Append per-request user content after the cache marker. Keep request structure byte-stable - even reordering JSON keys can bust the cache. Break-even on cache writes is under 2 reuses. ### Does Opus 4.7 support parallel tool calls? Yes. Opus 4.7 supports up to 16 concurrent tool calls per turn. Set `disable_parallel_tool_use: false` in the tool_choice parameter. The model will read multiple files and run multiple tests in a single assistant turn. This compresses wall time roughly 40% on multi-step agent loops. ### What is the context window for Opus 4.7? Opus 4.7 has a 1M token context window, now generally available on the standard tier without a flag. However, once a conversation crosses about 400K tokens, even Opus starts to drift on the earliest content. Periodically compact the transcript into a structured summary for best results. ### How does Opus 4.7 handle vision and image inputs? Vision quality improved significantly. Hand-drawn whiteboards, architecture diagrams, and dense product screenshots all transcribe better. In internal testing, false-route rates on Figma exports dropped from 18% to 6% compared to previous models.

Claude Vision API: Image Analysis At Production Scale

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Vision Looks Like Magic Until You Run 100k Images Through It The first time you hand Claude a screenshot and it correctly extracts every field on a messy invoice, the temptation is to stick that in a loop and bill your way to a finished product. Then the bill arrives, half your images came back with subtle hallucinations, and you discover the support team has been emailing you screenshots that are actually photos of laptop screens with glare on them. Claude's vision API is genuinely strong on structured imagery - documents, charts, diagrams, UI screenshots, code on screens. It is genuinely weak on the failure modes you only notice in production: low-resolution thumbnails, handwriting, rotated photos, images where the relevant content is 5% of the pixels. This guide covers the production patterns we use to ship vision pipelines that actually hold up at volume. We walked through some of the more counterintuitive tricks in our [Vision API Tricks: Extract Data from Screenshots](https://www.youtube.com/@developersdigest) video on YouTube. This post is the long-form companion. ## What Claude Vision Is Good At, And What It Isn't Claude reliably crushes: - **Structured documents** - invoices, receipts, tax forms, lab reports, anything with consistent layout - **Charts and graphs** - extracting series, axis labels, trend descriptions - **UI screenshots** - element identification, design feedback, accessibility audits - **Code-in-images** - copying code from a screenshot back into text with high fidelity - **Diagrams** - flowcharts, architecture diagrams, ER diagrams - **Tables** - even slightly skewed, multi-column tables come back clean Claude struggles with, in our experience: - **Handwriting** - better than it used to be, still unreliable on anything cursive - **Photos of screens** - the moire patterns and reflections murder accuracy - **Tiny detail** - anything smaller than ~12 pixels of feature size is a coin flip - **Counting** - "how many people are in this image" is genuinely hard for every vision model - **Spatial reasoning** in cluttered scenes - "is the cup to the left of the keyboard" Treat the second list as warning signs, not deal-breakers. With the right preprocessing and prompting, most of them get usable. Without it, you ship hallucinations. ## Image Input: Formats, Limits, And The Cost-Per-Pixel Reality Vision pricing is token-based, but the token count is computed from the image dimensions. The exact formula is roughly `tokens ~ (width x height) / 750`, capped after [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s resizing logic. Two practical consequences: 1. **A 2000x2000 image [costs](/blog/ai-coding-tools-pricing-comparison) about 5300 tokens of input.** That is not free. 2. **Resizing is your most powerful cost lever.** Most "high-resolution" images can be downscaled to 1024 pixels on the long edge with zero quality loss for documents and screenshots. Supported formats are JPEG, PNG, GIF, and WebP. You can pass a URL or base64. URL is preferable when you have a CDN; base64 is fine for pipelines that already have the bytes in memory. For most production workloads, the right preprocessing pipeline is: 1. Decode and auto-orient via EXIF 2. Convert to RGB 3. Downscale longest edge to 1568 pixels (Anthropic's preferred max) 4. Re-encode as JPEG quality 85 5. Hash the result for cache deduplication This typically cuts image costs 40 to 70% with no measurable accuracy loss on text-heavy imagery. ## The TypeScript Code You Should Actually Ship Here is a minimal but production-shaped vision call using the official Anthropic SDK. It accepts a base64 image, asks for structured extraction, and uses prompt caching on the instruction prefix so a high-volume pipeline does not pay full input cost on every call. ```typescript import Anthropic from "@anthropic-ai/sdk"; import sharp from "sharp"; const client = new Anthropic(); async function preprocessImage(buf: Buffer): Promise<{ data: string; mediaType: "image/jpeg" }> { const out = await sharp(buf) .rotate() .resize({ width: 1568, height: 1568, fit: "inside", withoutEnlargement: true }) .jpeg({ quality: 85 }) .toBuffer(); return { data: out.toString("base64"), mediaType: "image/jpeg" }; } const EXTRACTION_PROMPT = `You are a precise document extractor. Return only valid JSON matching: { "vendor": string, "date": string, "total": number, "line_items": [{"description": string, "amount": number}] } If a field is unreadable, use null. Do not invent values.`; export async function extractInvoice(imageBytes: Buffer) { const { data, mediaType } = await preprocessImage(imageBytes); const response = await client.messages.create({ model: "claude-sonnet-4-5", max_tokens: 1024, system: [ { type: "text", text: EXTRACTION_PROMPT, cache_control: { type: "ephemeral" }, }, ], messages: [ { role: "user", content: [ { type: "image", source: { type: "base64", media_type: mediaType, data }, }, { type: "text", text: "Extract this invoice." }, ], }, ], }); const text = response.content.find((b) => b.type === "text"); if (!text || text.type !== "text") throw new Error("no text response"); return JSON.parse(text.text); } ``` A few non-obvious things this shape captures: - The instructions are in `system` with `cache_control`, not in the user turn. Vision pipelines tend to have a stable instruction and a varying image; cache the stable part. - The image goes inside the user turn alongside a short text prompt. The text is what cues the model on what to do; without it, you get a generic description. - The response is parsed strictly. Vision models are slightly more prone to wrapping JSON in markdown - you can add a `` tag instruction or use a tool-use schema to lock it down. For schema-locked extraction, use tool use. Define a tool with the exact JSON Schema you want, force `tool_choice` to that tool, and you get back a guaranteed-valid object. We covered the details in [tool use patterns](/blog/tool-use-claude-api-production-patterns). ## Production Use Cases Where Vision Pays For Itself **1. Invoice and receipt OCR.** Vision plus a strict schema delivers extraction accuracy in the high 90s on real-world receipts - better than most dedicated OCR services on messy inputs, because Claude can reason about layout. Cost runs about $0.005 to $0.015 per receipt depending on resolution. **2. Bug-report screenshot triage.** Customer pastes a screenshot, vision extracts the visible error message, the URL bar, the browser, and the visible state. Auto-tagged into the issue tracker. We have seen support teams cut triage time by 60% on this single workflow. **3. UI accessibility audits.** Feed a screenshot of a page, ask for WCAG violations. Claude is shockingly good at "this contrast looks bad," "the touch target is too small," "this label is missing for the icon." Not a replacement for axe-core, but an excellent complement on visual issues automated tools miss. **4. Chart-to-data extraction.** Bar charts, line charts, scatter plots - Claude returns reasonable JSON of the underlying series. Watch out: numbers are estimates derived from pixels, not ground truth. Use it for "what is this chart showing," not for downstream analytics. **5. Diagram-to-code.** Hand-drawn architecture diagrams or flowcharts converted to mermaid, plantuml, or actual code stubs. Underrated workflow for design reviews. ## Building A Reliable Vision Pipeline Volume changes everything. At one image per minute you can ignore the failure modes; at 100k a month they dominate. The pipeline shape we have ended up with after several iterations: ``` [ingest] -> [validate] -> [preprocess] -> [hash + cache lookup] -> [vision call w/ retries] -> [schema validate] -> [confidence gate] -> [human review or auto-accept] -> [store + index] ``` Each step earns its keep: - **Validate.** Reject inputs that aren't actually images, are too small (under 200px on a side is a guarantee of garbage), or are corrupt. About 1 to 3% of inputs fail this gate in real apps. - **Hash + cache lookup.** A surprising fraction of "different" images are the same file uploaded twice. Hash the preprocessed bytes and skip the API call on duplicates. Easy 10 to 25% cost reduction. - **Schema validate.** Run the JSON response through Zod or your validator. About 0.5 to 2% of responses fail the schema even with strict prompting; retry once with a stricter prompt. - **Confidence gate.** Have the model return a `confidence` field, and route low-confidence outputs to human review. This is the single highest-impact reliability lever. For monitoring spend across a high-volume vision pipeline, [CodeBurn](/blog/codeburn-tui-dashboard-for-claude-code-token-spend) surfaces per-route token cost so you can tell instantly when an image-preprocessing regression doubles your bill. ## Handling Errors And Edge Cases The errors you will actually hit: - **`invalid_request_error: image too large`** - You sent over 5MB or over 8000px on a side. Preprocess. - **`overloaded_error`** - Vision endpoints get bursty. Exponential backoff with jitter. Three retries is enough. - **Truncated JSON** - Set `max_tokens` high enough. For invoice extraction, 2000 is safer than 1024. - **Confident hallucination** - The model returns a valid-looking number that doesn't exist in the image. The defense is a confidence-gated human review for any field used in money decisions. - **Mixed-language documents** - Claude handles them but sometimes returns translated values when you wanted the original. Always specify "return values exactly as printed, do not translate." ## Multi-Image Analysis And Sequence Reasoning You can pass multiple images in a single user turn. The model treats them as an ordered sequence. Common uses: - **Before/after comparisons** - "what changed between these two screenshots" - **Multi-page documents** - pass all pages of a PDF as separate images for end-to-end extraction - **Product image grids** - analyze a sheet of variants in one call Cost scales linearly with images. A four-image call costs roughly four times a one-image call (plus a small fixed overhead). For long documents, multi-image extraction in a single call is usually cheaper and more accurate than calling once per page, because the model can reason across pages. ## Production Gotchas Worth Pinning To Your Wall **1. EXIF orientation is not auto-applied.** A photo taken in portrait will land at the API rotated unless you bake the orientation into the bytes. We have seen entire pipelines fail because the iPhone landscape vs portrait flag was ignored. **2. Animated GIFs are sampled, not analyzed frame-by-frame.** You typically get the first frame. If you need video analysis, pass key frames as separate images. **3. The model will describe what it sees if you don't tell it not to.** Open-ended prompts like "what is this" produce flowery prose. For extraction, be explicit: return JSON only, no commentary. **4. Image content counts against the cache.** A cached system prompt plus an uncached image is the right pattern. You cannot meaningfully cache the image itself unless the exact same bytes recur, in which case do it via hash dedup at your layer. **5. PII in images is a real compliance issue.** Vision will happily extract SSNs, account numbers, faces. If you process user-uploaded images, run a redaction or detection pass and have an explicit data retention policy. Anthropic's data is not used for training by default on the API, but your own logs probably retain images longer than you think. **6. Resolution requirements vary by task.** UI screenshots can be downscaled aggressively. Tiny text in a fax-quality scan needs the full resolution. Don't blanket-downscale everything; route by content type. ## Scaling Vision At Production Volume For 100k+ images a month, three things matter more than the SDK call: - **Concurrency limits.** Anthropic's vision rate limits are tight. Use a token bucket and aim for ~80% of your stated limit. Bursting up to the limit causes more 529s than it earns in throughput. - **Async architecture.** Most vision workloads are not user-facing. Push them through a queue, return a job ID, notify on completion. For the truly batchable, the [Batch API](/blog/claude-batch-api-production-guide) cuts cost in half. - **Cost attribution.** Tag every call with the originating product and route. We have watched a single buggy feature triple a vision bill in a week because no one had per-feature attribution. The [400-Dollar Overnight Bill](/blog/400-dollar-overnight-bill-agent-finops) post-mortem walks through what bad attribution costs. ## Production Checklist Before You Ship - [ ] Image preprocessing: orient, resize to 1568px, JPEG q85 - [ ] Hash-based dedup cache in front of the API - [ ] System prompt cached with `cache_control` - [ ] Tool-use schema for any structured extraction - [ ] Schema validation on every response - [ ] Confidence field returned and gated for human review - [ ] Retry with backoff on overloaded errors - [ ] Per-feature token attribution logged - [ ] PII detection and retention policy on uploaded images - [ ] Async queue for non-interactive workloads - [ ] Alert on cost-per-image regressions Vision is the most under-used feature in the Claude API among teams that already have text working. The ones who get it right at scale treat it as an industrial pipeline, not a model call. Preprocess, cache, validate, attribute, and you will ship a vision feature that holds up. For more on shipping Claude in production, see our writeups on [prompt caching](/blog/prompt-caching-claude-api-production-guide) and [tool use patterns](/blog/tool-use-claude-api-production-patterns).

Cloudflare Agent Memory: A Developer's Guide to the New Primitive

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Why memory is the agent bottleneck If you have shipped a production agent in the last twelve months, you already know that memory is where the wheels come off. The model is not the bottleneck. The framework is not the bottleneck. The thing that keeps your agent from feeling like a real product is that it forgets everything between sessions and most things within a session. For the design side of the same problem, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) with [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they show how agent-generated interfaces fail and how to give coding agents better visual constraints. There are three workable answers to this in the open. You can run [mem0](https://mem0.ai) and pay for the managed service. You can roll your own with a vector store, a summarization pass, and a lot of glue code. Or you can wait for the platform you already deploy on to ship a memory primitive. Cloudflare just shipped that primitive. The [Agent Memory announcement](https://blog.cloudflare.com/introducing-agent-memory/) is the most opinionated take on agent state we have seen from a hyperscaler. It is worth comparing to mem0 directly because the two are aimed at exactly the same problem and they make very different tradeoffs. ## What the announcement actually says Cloudflare Agent Memory is a managed key-value-plus-vector store, scoped to an agent and an entity, accessible from Workers, Durable Objects, and the [Agents SDK](/blog/openai-agents-sdk-typescript). Three things make it different from "just use D1 plus Vectorize." It is entity-scoped. Memory is namespaced by agent id and entity id, typically a user, a session, or a tenant. The API does the partitioning for you, and the latency profile is tuned for "fetch this user's memory at the start of every turn." It is hybrid storage. Each memory item carries a key, a value, optional structured metadata, and an embedding. You can query by exact key, by metadata filter, or by semantic similarity. This collapses the typical "I have a key-value store and a vector store and they are out of sync" problem into a single API. It is pinned to the Workers runtime. Reads from a Worker in the same region as the memory store target single-digit milliseconds. Reads from the colocated Durable Object are even faster. This matters because agent memory is on the hot path of every turn. If the read [costs](/blog/ai-coding-tools-pricing-comparison) you fifty milliseconds, you feel it. The primitive ships with built-in summarization. You can write raw conversation turns and the platform will roll them up into stable summaries on a schedule. This is the piece that makes the long-tail memory problem tractable without you writing a summarization worker yourself. ## What it looks like in code The Agents SDK exposes memory through a single client. Here is a minimal turn handler that reads relevant memory, runs the model, and writes new memory back. ```typescript import { Agent, AgentMemory } from "@cloudflare/agents"; import { generateText } from "ai"; import { workersAI } from "@ai-sdk/workers-ai"; export class SupportAgent extends Agent { async onMessage(message: string, ctx: { userId: string }) { const memory = new AgentMemory(this.env.MEMORY, { agent: "support", entity: ctx.userId, }); const relevant = await memory.search({ query: message, limit: 6, filters: { kind: "preference" }, }); const recent = await memory.list({ kind: "turn", limit: 10, orderBy: "recent", }); const { text } = await generateText({ model: workersAI("@cf/meta/llama-3.3-70b"), system: this.buildSystem(relevant, recent), prompt: message, }); await memory.write({ kind: "turn", key: `turn-${Date.now()}`, value: { user: message, assistant: text }, embed: message, }); return text; } private buildSystem(relevant: any[], recent: any[]) { return `Known user preferences:\n${relevant .map((r) => `- ${r.value.fact}`) .join("\n")}\n\nRecent conversation:\n${recent .reverse() .map((t) => `User: ${t.value.user}\nAssistant: ${t.value.assistant}`) .join("\n")}`; } } ``` A few things to notice. The `kind` field is not magic. It is a metadata column you control. Use it to separate raw turns from extracted preferences from facts the agent has been told. The platform does not enforce a schema. That is your job. The filter syntax makes it cheap to keep them apart. The `embed` field at write time is what enables semantic search later. If you skip it, the item is stored but is only retrievable by key or metadata. For most agent workloads you want semantic on at least a subset of writes. The summarization layer, when enabled, runs as a Cloudflare-side job that walks `kind: "turn"` items and writes back `kind: "summary"` items on a configurable cadence. Your hot read path then queries summaries instead of raw turns, which keeps the context window manageable without you running a separate worker. ## Gotchas worth knowing The free tier is generous but vector queries are billed separately from key reads. If your agent does a hybrid read on every turn, the per-month math is reasonable for a small SaaS but can surprise you at scale. Profile early. Cross-region replication is eventually consistent. If your user moves between regions mid-conversation, you can briefly see stale memory. The platform converges fast, typically under a second, but a chat UI can render a turn before the write propagates. Plan for this in the UX or pin sessions to a region. The summarization layer is good but not magic. It will compress aggressively for long histories. If your agent depends on exact quotes from twenty turns ago, do not rely on summaries. Keep the raw turn store and pull from it explicitly when needed. Schema migrations are your problem. The platform does not version your memory shape. If you change what you store under `kind: "preference"`, write a migration that reads old shape and rewrites in new shape. There is no "memory ALTER TABLE." ## DD take: where it fits versus mem0 mem0 is the incumbent here, and the comparison is interesting because the two products target the same problem from different sides. mem0 is a managed service with a strong ergonomic story. The SDK feels designed for people who do not want to think about storage. It runs on its own infrastructure, exposes a clean REST API, and has the most mature schema for "extract preferences from raw turns automatically." If you are running outside Cloudflare and want a memory layer that feels like a finished product, mem0 is still the answer. Cloudflare Agent Memory is a primitive. It assumes you are already in the Workers runtime and gives you the lowest-latency, most-integrated path to durable agent state on that platform. The semantic retrieval, the summarization, the entity scoping are all present, but the API is closer to "managed database" than "finished memory product." You will write more code, and you will get more control. The right way to choose is by deploy target. If your agent runs on Workers, Cloudflare Agent Memory is the obvious primitive. The latency advantage on the hot path is large enough to matter. If your agent runs on Vercel, AWS, or Fly, mem0's portability is the clearer win. Mixing the two is possible but probably overkill for an indie team. Cost-wise, both are reasonable for small to medium scale. At very high write volumes, the Cloudflare model wins on the per-write cost. At very high read volumes with complex semantic queries, the math gets closer. ## Wiring it into a real product We have been integrating Agent Memory into [AgentFS](https://agentfs.developersdigest.tech), our virtual filesystem layer for AI agents that gives them durable, sandboxed working storage across runs. AgentFS started as a thin wrapper over R2 and Durable Objects to give agents a persistent `/workspace` directory between sessions. The memory primitive lets us layer a richer abstraction on top: the agent's beliefs about the workspace, not just the raw bytes in it. The pattern is straightforward. AgentFS stores files in R2. Cloudflare Agent Memory stores the agent's notes about those files - what they are, what changed last session, what the user wanted - keyed by file path with semantic search over the notes. The agent walks into a new session, queries memory for "what was I working on in this directory," and gets back the relevant notes without scanning the whole filesystem. For observability, [Traces](https://traces.developersdigest.tech) reads from the same memory store to render a session timeline. Every memory read and write is a trace event, and the UI shows you which memories influenced the model's output on each turn. This turns out to be the killer debug tool for agent memory. Without it, you are guessing about why the agent forgot something or why it remembered something it should not have. With it, you can scroll the timeline and see exactly which memory keys were in context. Wiring memory into a real product is not just about storage. It is about understanding what the agent saw and when. That is a tooling problem as much as an infrastructure problem. ## What to watch next The interesting open questions. Cross-agent memory. Right now memory is scoped to one agent id. Real product use cases - a customer support agent that needs to know what the sales agent told the user yesterday - require cross-agent memory or a shared memory layer. Cloudflare has hinted at this but not shipped it. mem0 already supports it. Memory pruning policy. The platform stores everything you write, indefinitely. For GDPR and product hygiene, you need a deletion API and ideally a TTL primitive. Both exist, but the ergonomics are not where they should be yet. The "memory as a graph" question. The current API is flat: keys, values, embeddings, metadata. Some of the most interesting agent memory research is about graph structures over those memories. Whether platforms ship graph-native memory or push it to userland is the next architectural decision worth tracking. We are running a [deeper hands-on walkthrough on YouTube](https://youtube.com/@DevelopersDigest), building a customer support agent that uses Cloudflare Agent Memory end to end, with debug traces and a side-by-side comparison against mem0. If you are picking your memory layer this quarter, that comparison is the thing to watch. The platforms have converged faster than expected, and the choice is now mostly about deploy target rather than capability.

Flagship: Cloudflare Feature Flags for AI Apps

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Flags For AI Are Different Every team running AI in production eventually rebuilds the same three things on top of LaunchDarkly or Statsig: a model selector keyed by user cohort, a kill switch for runaway agents, and a prompt template registry that does not require a deploy. Generic flag systems treat these as the same primitive, a boolean or a string, and let you figure out the rest. For broader context, pair this with [Every AI Coding Tool Compared: The 2026 Matrix](/blog/ai-coding-tools-comparison-matrix-2026) and [What Is an AI Coding Agent? The Complete 2026 Guide](/blog/what-is-an-ai-coding-agent-2026); those companion pieces show where this fits in the wider AI developer workflow. [Cloudflare Flagship](https://blog.cloudflare.com/flagship/), announced this week, ships with these three patterns as first-class concepts. It is not just a flag store. It is a control plane for AI behavior: model selection with cost-aware routing, prompt versioning with rollback, and gates with real-time circuit breaking. All of it evaluated at the edge with single-digit millisecond latency. This is the primitive every AI app already has, written badly, in your own codebase. The question is whether replacing it with a hosted service is worth the migration. For most teams, yes. Here is why and how. ## What Flagship Actually Ships The [announcement](https://blog.cloudflare.com/flagship/) lists four headline capabilities, but only three of them matter for AI apps. **Model flags** are typed flag values that resolve to a model identifier plus optional config (temperature, max tokens, system prompt overrides). You define them once and reference them everywhere. Cohort targeting, gradual rollouts, instant rollback all work the same as a normal flag. **Prompt registry** stores versioned prompt templates and resolves them at request time. Each version is addressable, every evaluation is logged, and rollback is a click. This solves the "we changed the system prompt and broke production at 2am" problem by making the change a first-class event with a diff. **Circuit breakers** are flags that auto-flip based on rules you define against your own metrics. Error rate above 5% on this model, flip to the fallback. Cost per user above the threshold, flip to a smaller model. This is the piece that you cannot easily build on top of a generic flag service because it requires the flag system to consume your telemetry and write back to itself. The fourth capability, A/B testing dashboards, is competent but not differentiated. Use it if you are not already wired into a stats platform. Skip it if you are. ## What It Looks Like in Code The integration is intentionally thin. A single call per flag, evaluated at the edge or in your worker. ```ts import { Flagship } from "@cloudflare/flagship"; const flags = new Flagship({ token: process.env.FLAGSHIP_TOKEN }); export default { async fetch(req: Request, env: Env): Promise { const userId = req.headers.get("x-user-id") ?? "anon"; // Model flag with full config payload const modelConfig = await flags.model("primary_chat_model", { user: { id: userId }, defaults: { provider: "anthropic", model: "claude-sonnet-4.7", temperature: 0.7, }, }); // Prompt flag: resolves to a versioned template const systemPrompt = await flags.prompt("chat_system_prompt", { user: { id: userId }, variables: { product_name: "Acme" }, }); // Circuit-broken tool gate if (!(await flags.gate("agent_tools_enabled", { user: { id: userId } }))) { return Response.json({ error: "Agent temporarily unavailable" }); } const body = await req.json(); const reply = await callModel({ ...modelConfig, system: systemPrompt, messages: body.messages, }); // Report outcome: circuit breakers consume this await flags.report("primary_chat_model", { latency_ms: reply.latency, error: reply.error ? 1 : 0, cost_usd: reply.cost, }); return Response.json(reply); }, }; ``` The shape worth noting: `flags.report` closes the loop. The same flag that resolved the model also consumes the outcome. If error rate spikes, the circuit breaker rule you defined in the dashboard flips the flag to the fallback model automatically. No human in the loop, no PagerDuty page at 3am. ## The Gotchas **Edge eval means edge eval.** Flagship runs on Cloudflare's edge, which is a feature if your app is also on the edge and a tax if you are running on AWS in us-east-1 with no edge tier. The flag fetch adds 30-60 ms in that case. For most AI apps that is a rounding error against the model latency, but if you are doing high-frequency flag evaluations inside a tight loop you will feel it. **Prompt templates are not Jinja.** The variable substitution syntax is intentionally simple: `{{var}}` and basic conditionals. If you need real templating logic, render the prompt in your code and pass the rendered string as a variable. Trying to fit complex prompt construction into the registry is the path to pain. **Circuit breaker rules can deadlock.** If your fallback model is also a flag with its own circuit breaker, and both fail, you can end up flipped to a third option you did not intend. Always define a hard-coded last-resort default in your code that does not go through the flag system. This is not a Flagship-specific problem but it is more visible here because the system encourages cascading flags. **Flag values are eventually consistent.** A flip in the dashboard takes 5-15 seconds to propagate globally. For incident response that is fine. For experimentation it is fine. For "I just deployed this and want to test it" it is annoying enough that you should keep a local override mechanism. ## Where It Fits in the Agent Stack Flag systems sit at an awkward layer in the agent stack. Above your inference layer because they decide which model to call. Below your orchestration layer because the orchestrator does not care about the flag, only the resolved value. Adjacent to observability because the flag system consumes metrics to trigger circuit breakers. The clean way to slot Flagship in: it owns the "what model, what prompt, what tools" decision for every agent invocation. Your orchestrator owns the workflow. Your observability owns the truth. Flagship reads from observability and writes to the orchestrator's input. This matters when you are running multi-step agent workflows because each step is an independent decision. Step 1 plans, step 2 executes, step 3 verifies. Each step might want a different model: opus for planning, sonnet for execution, haiku for verification. Each model selection can be a separate flag. We use this pattern inside [Orchestrator](https://orchestrator.developersdigest.tech), our DD product for declarative multi-agent workflows. Each node in the graph reads its model and prompt from Flagship at execution time, which means we can tune the entire graph from a dashboard without redeploying any worker. The other place flags compose well is observability replay. When you see a bad agent run, you want to know not just the prompt and response but the flag values that were active when the run executed. Recording flag context with every trace is the difference between "we cannot reproduce this" and "the user was in cohort B with the experimental prompt." [Traces](https://traces.developersdigest.tech) records every flag value alongside the agent transcript, which is the integration that closes the debugging loop. I walked through the full setup including circuit breaker rules and rollout strategies on the [Developers Digest YouTube channel](https://youtube.com/@DevelopersDigest). ## Wiring It Into A Real Product A few patterns that have worked across the agent products we run. Start with one flag: model selection. That is the highest-value, lowest-risk place to begin. Wrap your existing model call in a Flagship lookup, set the default to your current model, deploy. You now have an instant kill switch and a path to A/B testing. Everything else is incremental. Version every prompt change as a new prompt flag value, not an edit to the existing one. The audit trail is worth the minor overhead, and rollback becomes trivial. We rotate to a new version of every prompt every time we change it, with the old version archived but reachable. Define circuit breakers conservatively at first. A 10% error rate threshold with a 5-minute window is a safe starting point for most apps. Tighten it as you learn what normal looks like. Aggressive thresholds on day one will flap. Keep a hard-coded last-resort default in code for every flag. If Flagship is unreachable, your app should still work, just on the safe defaults. Treat the flag service as a control plane, not a single point of failure. ## What To Watch Next Two things to keep an eye on. First, whether Cloudflare adds first-class evals as a sibling to flags. The natural integration is "tie a flag rollout to an eval pass rate", only promote to 100% when the eval suite holds at green. Right now you have to glue that together with your own pipeline. Building it natively would eat a real product category. Second, whether the prompt registry gains structured types. Right now prompts are strings with variables. The interesting future is prompts as typed schemas with input validation and output parsing baked in. That would make Flagship a competitor to LangSmith's prompt hub, which is the obvious adjacent target. For now the move is simple. Take the worst part of your AI app, the place where you are deploying just to change a model name, or hand-editing a prompt in production, or hoping nothing breaks because you have no kill switch, and replace it with a flag. The control plane you have been pretending you do not need is the one Cloudflare just shipped.

Codex Security Preview: AppSec Agent for Real Repos

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

OpenAI shipped Codex Security in research preview, and the framing matters. This is not a glorified linter and it is not a wrapper around Bandit, Semgrep, or CodeQL. It is an agent that reads your repository, understands the call graph, hypothesizes attack paths, and writes up findings the way a junior application security engineer would. I pointed it at three open source repositories with known CVEs, plus a private one we use internally for CI tooling, and tracked exactly what it caught and what it missed. This post is the truth about its catch rate, where it fits in a real SDLC, and the operating posture I would recommend if you get into the preview. ## What Codex Security Actually Is Most static analysis is pattern matching. The tool has a database of known dangerous patterns, scans your code, and reports any matches. This catches obvious bugs but misses anything that requires reasoning about how data flows across files, how authentication is structured, or how a feature is actually used. For the security frame around this, see [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); both focus on the places where agent autonomy needs explicit boundaries. Codex Security is agentic. It treats your repository the same way a Codex [coding agent](/blog/what-is-an-ai-coding-agent-2026) would: it can read files, follow imports, execute searches, and build a working model of the application. It then proposes hypotheses about where vulnerabilities could exist, investigates each one, and reports findings with reproduction steps and suggested fixes. The shift from "look for known patterns" to "reason about this specific application" is the same shift that happened from rule-based to ML-based tooling a decade ago, but the unit of reasoning is now the application itself rather than the line. That is what makes it interesting and also what makes it dangerous. ## Joining the Research Preview Access is gated. You request an org-level enrollment and get a quota of agent runs per day. The preview is rate-limited per repo, which means you cannot point it at every repo in your org on day one. I would recommend prioritizing your highest blast-radius services: anything that handles auth, billing, or PII. Save the rest for when GA [pricing](/blog/ai-coding-tools-pricing-2026) lands. The integration is straightforward. You point Codex Security at a repo, optionally scope it to a path or a PR diff, and it streams findings back. I run it from the API directly because I want findings in our existing security pipeline, not in a separate dashboard. ```python from openai import OpenAI client = OpenAI() scan = client.responses.create( model="gpt-5.3-codex", input=[ { "role": "developer", "content": ( "You are a senior application security engineer. " "Audit the attached repository for vulnerabilities in: " "authentication, authorization, input validation, " "SSRF, SQL injection, and secrets handling. " "For each finding, return JSON with: severity, file, line, " "description, exploit_scenario, and suggested_fix." ), }, { "role": "user", "content": "Repository: github.com/acme/payments-api at commit 8a3f9c2", }, ], tools=[ {"type": "code_interpreter", "container": {"type": "auto"}}, {"type": "file_search"}, ], reasoning={"effort": "high"}, response_format={"type": "json_object"}, ) findings = scan.output_text ``` That is essentially the agent loop. Behind the scenes the model uses tools to clone the repo into a sandboxed container, walks the codebase, and emits structured findings. You can wire that JSON into your existing tracker, dedupe against last week's run, and only surface new issues to humans. ## My Benchmark Setup Three open source repositories, each seeded with a small number of intentionally broken commits I authored, plus the existing CVE history of the project. Each commit introduced exactly one bug from a known vulnerability class, with the file and line documented in a private ground-truth list. Repo A was a Node.js Express API with seeded SQL injection, an SSRF in a webhook handler, and an authorization-bypass where a user-controlled `role` field was trusted from the request body. Repo B was a Python FastAPI service with seeded path traversal in a file download endpoint, a hardcoded HMAC secret, and a race condition in a balance update. Repo C was a Go HTTP service with seeded server-side template injection, an open redirect, and a misconfigured CORS that allowed arbitrary origins with credentials. Plus the natural CVE history each project carried before I touched it. Total ground truth: 23 issues across the three repos. I also wired the agent runs through [DD Traces](https://traces.developersdigest.tech) so I could replay each scan, look at the tool calls, and audit which files the agent read. Without traces you cannot tell whether a missed vulnerability was a reasoning failure or simply a file the agent never opened. With traces, the post-mortem is straightforward. ## What It Found Codex Security caught 16 of the 23 seeded or historical issues across the three repos. That is a 70% catch rate, which sounds modest until you read the findings. The SQL injection in Repo A was caught with a clean exploit scenario, including the exact crafted payload, and a fix that used the parameterized query API the codebase already had elsewhere. The agent had clearly read three other endpoints in the same router and noticed the pattern was inconsistent. The SSRF in Repo A was caught and, more impressively, the agent flagged a second related issue I had not seeded. The webhook handler trusted a user-supplied URL without validating the scheme. I had seeded an SSRF where the URL was used directly. The agent noticed the same URL was logged later via a different code path that also performed an HTTP fetch in a debug branch. That second path was a real issue I had not noticed. The hardcoded HMAC secret in Repo B was caught immediately and the suggested fix was correct: move to environment variables, rotate the key, document the rotation procedure. The agent also noticed the secret had been committed for two years and recommended a git history rewrite, which is the right call. The CORS misconfiguration in Repo C was caught with a clear writeup of why `Access-Control-Allow-Origin: *` combined with `Allow-Credentials: true` is not just wrong but actively dangerous, and a fix that locked the origin list down to the canonical domains. There were two surprising catches that were not on my ground-truth list. In Repo B the agent noticed that a JWT verification path skipped the audience claim, which meant tokens issued for a sibling service would validate. In Repo C it flagged a `time.Now().UnixNano()` used as a session token seed, which is a real entropy issue. Both were legitimate, both were not seeded, and both were findings I would have wanted from a human reviewer. ## What It Missed The misses tell you more about the boundaries than the hits do. It missed the authorization bypass in Repo A. The user-controlled `role` field in the request body was trusted without verification, but the bug only surfaced if you traced the request through three middleware layers and noticed that the role check happened against the request body rather than the session. Codex Security read the endpoint and the immediate handler but did not climb up into the middleware to verify the auth assumption. This is the classic auth-flow blind spot for any tool that reasons primarily about a single file or a single endpoint. It missed the race condition in Repo B. The balance update path read, computed, and wrote without a transaction. Static-analysis tools usually miss these because the bug only exists in concurrent execution, not in the source. Codex Security is no different. The fix would require either explicit concurrency reasoning prompts or a runtime fuzz harness, neither of which is in the preview today. It missed the path traversal in Repo B. This one was a tooling issue more than a reasoning issue. The agent never opened the file containing the download handler because it was nested in a deprecated module that was still wired in via a router include. The trace made that clear. If your repo has dead-looking modules that are actually live, scope the scan explicitly. It missed the open redirect in Repo C. This was the closest to a true reasoning failure. The agent identified the redirect endpoint, noted that it accepted a query parameter, and concluded that an allowlist check existed elsewhere. There was no allowlist, but the agent had seen a similarly named function in another file and assumed it applied. Honest mistake, and one that a careful human reviewer would also have to verify. It missed business-logic vulnerabilities entirely. None of the three repos had seeded business-logic bugs because I was not testing for them, but I want to call this out: agentic AppSec today is good at vulnerability classes that have a recognizable code shape and weak at vulnerabilities that depend on understanding intent. A coupon system that allows negative discounts will not be flagged because there is nothing in the code that looks dangerous. That requires product context the model does not have. ## Where It Slots Into A Real SDLC Pre-commit is the wrong slot. Run times are too long, the agent needs to understand the full repo to be useful, and most pre-commit checks should be deterministic. Skip it. PR-bot is the right slot for findings discovery, but with discipline. Run Codex Security on the diff plus the immediate import graph, treat all findings as draft, and have a human triage before anything blocks the merge. Auto-blocking on agent findings is not ready for the preview. False positive rates are still high enough that you will erode trust quickly. CI is the right slot for full-repo scans, scheduled nightly or weekly, with results piped into your existing ticketing system. Dedupe against the previous run, only file new tickets for new findings, and tag findings with the agent's confidence level if you can extract it from the response. The patterns I use here are borrowed wholesale from [SkillForge CI](https://github.com/developersdigest/skillforge-ci), which we built for general agent CI workflows. The same primitives, scoped runs, structured outputs, dedup-against-baseline, apply to AppSec agents directly. If you are wiring this into your own pipeline, that repo is where I would start. For the visual walkthrough of running Codex Security against a real repo and triaging findings live, the [DevDigest YouTube hands-on video](https://www.youtube.com/@DevelopersDigest) covers the full flow, including the trace replay of one of the catches I described above. ## Final Take Codex Security is the first AppSec agent I have used that I would describe as a genuine review partner rather than a noisy scanner. It catches things a junior engineer would catch, occasionally things a mid-level engineer would miss, and it explains itself well enough that triaging is fast. It is not yet a replacement for a security engineer. It misses auth flows, business logic, and concurrency. It will hallucinate the existence of safety checks that are not there. The preview rate limits will stop you from running it across an entire org on day one. But the trajectory is real. If you have access to the preview, the highest-value thing you can do this week is wire it into your CI on one critical service, run it nightly for a month, and build your own ground-truth list of what it catches. By the time GA lands, you will have a calibrated sense of what to trust and what to verify, and that is worth more than any benchmark anyone else publishes.

Gemma 4: The Open Model Guide for Developers

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The most credible open Google model yet Google has shipped open-weights models before. Gemma 1 was a respectable showing. Gemma 2 closed the gap. Gemma 3 was genuinely competitive. [Gemma 4 is the first time](https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/) the company has released an open model that you can credibly drop into a production stack and not feel like you are choosing between "open" and "good." For model-selection context, compare this with [AI Design Slop: 15 Patterns That Out Your App as Vibe-Coded](/blog/ai-design-slop-and-how-to-spot-it) and [Create Beautiful UI with Claude Code: The Style Guide Method](/blog/create-beautiful-ui-claude-code); the useful question is not only benchmark quality, but where the model fits in a real developer workflow. That matters because the open-weights conversation in 2026 is not theoretical anymore. Llama, Mistral, Qwen, [DeepSeek](/blog/deepseek-v4-developer-guide), and now Gemma are all serious. The question developers are actually asking is which one to bet on, and the answer depends on three things that Gemma 4 happens to do well: deployment ergonomics, license clarity, and downstream tunability. This is the deploy playbook. What it is, how to run it locally, how to fine-tune it, and where it fits in the agent stack. ## What shipped Gemma 4 came out in three sizes: 2B, 9B, and 27B parameters. Multi-modal across text and images on the larger two. Context length is 128K tokens. The license is the same Gemma terms that allow commercial use with attribution and a permissible use policy. Weights are on Hugging Face, Kaggle, and Google's own model hub. The headline numbers are competitive at every size class. The 27B sits in the same neighborhood as [Llama](/blog/llama-4-developers-guide) 3.3 70B on most reasoning benchmarks while running at less than half the inference cost. The 9B is the sweet spot for most application work, fitting comfortably on a single 24GB consumer GPU at 4-bit quantization. The 2B is the on-device tier, targeting laptops, phones, and edge inference. The architectural changes from Gemma 3 are incremental but useful. Improved sliding-window attention for long contexts. Better RoPE scaling. A tokenizer that handles code and structured output noticeably better than the previous generation. The image encoder on the multi-modal variants is the same family that ships in [Gemini](/blog/gemini-deep-research)'s smaller tiers, which means quality is meaningfully ahead of bolt-on vision adapters. ## Running it locally with Ollama The fastest path to having Gemma 4 on your laptop is Ollama. The Ollama team typically ships day-zero support for new Google models, and Gemma 4 was no exception. ```bash ollama pull gemma4:9b ollama run gemma4:9b "Explain GRPO in two sentences." ``` That is the entire setup on a Mac with at least 16GB of unified memory. The 27B variant needs 32GB or better. The 2B runs comfortably on anything with a GPU made in the last five years. For programmatic access: ```python import ollama response = ollama.chat( model="gemma4:9b", messages=[ {"role": "user", "content": "Write a Python function to flatten a nested list."} ], ) print(response["message"]["content"]) ``` If you want streaming, [OpenAI](/blog/openai-vs-anthropic-2026)-compatible endpoints, or multi-model serving on the same box, Ollama exposes all of that on `localhost:11434`. The mental model is "drop-in OpenAI replacement that runs on your machine." ## Running it on a serious GPU with vLLM For production inference, Ollama is not the right tool. vLLM is. The throughput difference at batch size greater than one is roughly an order of magnitude. ```bash pip install vllm vllm serve google/gemma-4-9b-it \ --max-model-len 32768 \ --gpu-memory-utilization 0.9 \ --tensor-parallel-size 1 ``` That spins up an OpenAI-compatible server on port 8000. You hit it with the standard openai client by pointing `base_url` at your server. ```python from openai import OpenAI client = OpenAI(base_url="http://localhost:8000/v1", api_key="not-needed") response = client.chat.completions.create( model="google/gemma-4-9b-it", messages=[{"role": "user", "content": "Generate 5 startup ideas about open weights."}], max_tokens=512, ) print(response.choices[0].message.content) ``` A few production considerations worth pinning down before you ship this in front of users. **Quantization.** vLLM supports AWQ and GPTQ quantizations of Gemma 4. The 9B at 4-bit fits comfortably on a 24GB card with 32K context. The 27B at 4-bit needs 48GB. Quantization quality on Gemma 4 is unusually good. The published 4-bit AWQ checkpoints lose less than a point on most benchmarks compared to the bf16 baseline, which is meaningfully better than the same pattern for Llama-class models. **Batching.** Throughput climbs steeply with batch size. If your workload is a steady stream of requests, vLLM's continuous batching pulls 5 to 10 times more tokens per second per GPU than a naive serving setup. **Long context.** The 128K window is real. It is also expensive. KV cache memory is the bottleneck. Plan for context length carefully if you are serving many concurrent requests, and consider whether your application actually needs the full window or whether 32K suffices. ## Fine-tuning with TRL or Unsloth Most developers will not need to pretrain Gemma 4. Most developers will need to fine-tune it on their specific task. Two paths, both tractable. For LoRA fine-tuning at scale, TRL is the canonical tool: ```python from trl import SFTTrainer, SFTConfig from datasets import load_dataset from peft import LoraConfig dataset = load_dataset("your-org/your-task", split="train") lora_config = LoraConfig( r=16, lora_alpha=32, target_modules=["q_proj", "k_proj", "v_proj", "o_proj"], lora_dropout=0.05, ) trainer = SFTTrainer( model="google/gemma-4-9b-it", train_dataset=dataset, peft_config=lora_config, args=SFTConfig( output_dir="gemma4-finetuned", num_train_epochs=3, per_device_train_batch_size=2, gradient_accumulation_steps=8, learning_rate=2e-4, bf16=True, ), ) trainer.train() ``` For solo developers on a single GPU, Unsloth is the speed-and-memory winner. Same API surface as TRL, roughly twice as fast, half the memory, and Gemma 4 is one of the supported models from launch: ```python from unsloth import FastLanguageModel model, tokenizer = FastLanguageModel.from_pretrained( model_name="unsloth/gemma-4-9b-it", load_in_4bit=True, max_seq_length=8192, ) model = FastLanguageModel.get_peft_model(model, r=16) # ... use it with your existing trainer ``` The main gotcha across both paths is the chat template. Gemma 4 uses a specific turn-marking format with `` and `` tokens. If you assemble training data with the wrong template, the model trains fine but generates with the wrong stop tokens at inference. Use `tokenizer.apply_chat_template` rather than rolling your own format strings. This bites someone every release cycle. ## Where Gemma 4 fits in the agent stack Honest framing: Gemma 4 is not the best model in the world. The frontier closed-weights tier still outperforms it on the hardest benchmarks. What it is, is the best open model in the small-to-mid size class, with a license that lets you ship it commercially without a lawyer present. That makes it the right choice for several specific jobs. **On-device inference.** The 2B is small enough to run on a phone with no API key, no network round trip, and no per-call cost. For features that need a small model close to the user, Gemma 4 2B is the default starting point. The latency profile is usable for interactive features, not just background batch jobs. **Self-hosted production with privacy constraints.** If your data cannot leave your network, Gemma 4 9B on a single GPU at 4-bit is the path. It is not GPT-4. It is good enough for most production tasks and your data never crosses a wire. For regulated industries this is the entire ballgame. **Fine-tuned domain experts.** A specialized 9B fine-tuned on your domain typically beats a generalist GPT-4 call for that domain, at a fraction of the inference cost. Gemma 4 is a particularly good base for this because the chat-tuned variant is well-aligned out of the box and does not require extensive retraining to make it usable. **Cost-sensitive agent loops.** Agent loops burn tokens. An agent that makes ten tool calls per task is paying ten times the per-token cost. Self-hosted Gemma 4 on commodity hardware drops the marginal cost to near-zero, which changes the design space for what agent loops are economically viable. We run small-model agents on this profile inside [AgentFS](https://agentfs.developersdigest.tech), where the orchestrator handles tool dispatch and the model only needs to be smart enough to pick the right tool and format the call. Gemma 4 9B fine-tuned on tool-call traces handles that with room to spare. For exposing the agent's tool surface as MCP servers, we pair it with [MCPaaS](https://mcpaas.developersdigest.tech), which makes the model's tool registry a managed service rather than a per-app concern. The walkthrough video for the full deploy-and-fine-tune pipeline is on the [DevDigest YouTube channel](https://youtube.com/@DevelopersDigest), including a side-by-side comparison of Gemma 4 9B against the closed-weights peers on the same agent task. ## What to watch next Three threads worth following over the next quarter. **The 70B variant.** Google has not announced a Gemma 4 in the 70B class. The gap between 27B open and frontier closed is real, and a 70B Gemma would close most of it. If it ships, it changes the calculus for self-hosted production work meaningfully. **Gemma-specific reasoning fine-tunes.** DeepSeek R1's recipe is being applied to every credible open base, and Gemma 4 will be no exception. Expect community-trained "Gemma 4 R1" variants within weeks. Some will be excellent. Watch the leaderboards rather than the announcements. **Multi-modal tool use.** The image encoder on Gemma 4 is good. Tool-use benchmarks for vision-language models on agent tasks are still immature. There is a real opening for someone to build the first credible open multi-modal agent on top of Gemma 4 27B and publish numbers that the rest of the field has to chase. The takeaway is simple. If you are picking an open-weights base today, Gemma 4 is on the short list. If you have not run it locally yet, the Ollama command above takes thirty seconds. Do that first, see how it feels, then decide where it fits.

DeepSeek V4: The Developer's Guide to Flash and Pro

Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## DeepSeek V4 Is Here, And It Is Not One Model DeepSeek dropped V4 over the weekend and the rollout is bigger than V3 was. Instead of a single flagship plus a reasoning sibling, V4 ships as a family. There is **DeepSeek V4 Flash** for everyday work and **DeepSeek V4 Pro** for the heavy lifting. Both models fold reasoning into the same checkpoint, both stretch the context window to one million tokens, and both undercut every closed frontier model on price by roughly an order of magnitude. If you were already running DeepSeek R1 or V3 in production, V4 is a drop-in upgrade with one config change. If you were on Claude or GPT for cost-sensitive workloads, V4 is the model that finally makes the switch worth running the numbers on. We covered the launch on the channel in [DeepSeek v4 in 4 Minutes](https://youtu.be/Oi6pQmGjH7Y), but the four-minute version skips the parts that matter when you actually wire it into an app. This is the longer take. ## The Family: Flash vs Pro DeepSeek collapsed the old `deepseek-chat` and `deepseek-reasoner` endpoints into a single API surface that splits on model tier instead of on whether reasoning is on or off. Reasoning is now a runtime parameter, not a separate model. ### DeepSeek V4 Flash Flash is the small, fast tier. The model card on Hugging Face lists it at 158B total parameters with a smaller active footprint per token. It is built for high-throughput, latency-sensitive work: chat UIs, autocomplete, classifiers, [RAG](/blog/what-is-rag) retrieval rerankers, agent inner loops. The full chain-of-thought trace is available if you ask for it, but Flash defaults to non-thinking mode, which keeps response times in the same ballpark as the older `deepseek-chat`. Flash also gets the legacy aliases. If your code is still pointed at `deepseek-chat` or `deepseek-reasoner`, those names will keep resolving until 24 July 2026, both backed by V4 Flash with thinking off and on respectively. Migrate when you have a quiet afternoon. ### DeepSeek V4 Pro Pro is the new flagship. The base checkpoint weighs 1.6T parameters, with the released instruction-tuned model at 862B total. This is the model you pull out for hard reasoning: long-horizon coding tasks, multi-step planning, dense math, agent workloads where the model has to keep its own state across many tool calls. It is slower than Flash and several times more expensive, but still cheaper than Claude Sonnet 4 or GPT-5 for the same task. Both tiers share a 1M token context length and a maximum output of 384K tokens. The 384K output number is the one nobody else is matching right now. If you are doing long-form generation, codebase rewrites, or full-document translations, that headroom is the difference between one call and a stitched chain. ## Pricing: The Number That Moved The Market Here is the current API pricing per million tokens, taken from the live docs as of this morning. | Model | Cache hit input | Cache miss input | Output | |-------|----------------|------------------|--------| | DeepSeek V4 Flash | $0.0028 | $0.14 | $0.28 | | DeepSeek V4 Pro (launch discount) | $0.003625 | $0.435 | $0.87 | | DeepSeek V4 Pro (full price) | $0.0145 | $1.74 | $3.48 | | Claude Sonnet 4 (reference) | $0.30 | $3.00 | $15.00 | | GPT-5 (reference) | ~$0.40 | ~$2.50 | ~$10.00 | A few things worth flagging. The cache hit price on Flash is **$0.0028 per million input tokens**. That is not a typo. DeepSeek dropped the cache hit price to one tenth of the launch number on 26 April, and Flash is now the cheapest serious model to call repeatedly with stable system prompts. Build with cache-friendly prompt structure and your input bill effectively disappears. V4 Pro is running at a 75 percent launch discount through 31 May 2026. After that the price triples. If you are evaluating Pro, evaluate it now. The full-price column is the long-term number you should be modelling against. ## OpenAI-Compatible Setup, In One Block The DeepSeek API speaks the OpenAI Chat Completions dialect, plus an [Anthropic](/blog/anthropic-vs-openai-developer-experience)-compatible endpoint if you prefer that SDK. The cleanest path is the OpenAI Python SDK with a custom `base_url`. ```python import os from openai import OpenAI client = OpenAI( api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com", ) response = client.chat.completions.create( model="deepseek-v4-flash", messages=[ {"role": "system", "content": "You are a senior backend engineer."}, {"role": "user", "content": "Write a FastAPI endpoint that streams SSE events from a Postgres LISTEN/NOTIFY channel."}, ], stream=True, ) for chunk in response: delta = chunk.choices[0].delta.content if delta: print(delta, end="", flush=True) ``` That is the whole integration. Swap `deepseek-v4-flash` for `deepseek-v4-pro` when you need the bigger model. The TypeScript SDK is identical with the obvious syntax changes. ### Turning On Thinking Mode Flash defaults to non-thinking. To get the reasoning trace, pass an extra body parameter. The current docs use `thinking` on the request payload. ```python response = client.chat.completions.create( model="deepseek-v4-flash", messages=[{"role": "user", "content": "Find the bug:

"}],
    extra_body={"thinking": {"enabled": True}},
)

reasoning = response.choices[0].message.reasoning_content
answer = response.choices[0].message.content
```

The thinking trace comes back on `reasoning_content`, the final answer on `content`. Same shape as the OpenAI o-series response, which means most [agent frameworks](/blog/ai-agent-frameworks-compared) already know how to read it.

### Tool Calling

Tool calling works the same way it does on [OpenAI](/blog/openai-vs-anthropic-2026). Pass a `tools` array with JSON schema, the model returns `tool_calls`, you execute and feed results back in. There is one wrinkle: V4 Pro with thinking enabled produces a noticeably better tool plan than V4 Flash on multi-step agent tasks. If your agent is making the wrong tool choice, that is the first thing to flip.

## Benchmarks: V4 vs R1 vs V3

DeepSeek published their own benchmark numbers with the launch. I have not yet seen independent third-party verification, so treat these as the vendor's view. They line up with the early community reports on Hugging Face.

| Benchmark | V3 (Mar 2025) | R1 (Jan 2025) | V4 Flash | V4 Pro |
|-----------|---------------|----------------|----------|--------|
| MMLU-Pro | 75.9 | 84.0 | 81.4 | 88.7 |
| MATH-500 | 90.2 | 97.3 | 95.8 | 98.4 |
| AIME 2024 | 39.6 | 79.8 | 74.2 | 86.1 |
| GPQA Diamond | 59.1 | 71.5 | 70.8 | 78.3 |
| LiveCodeBench | 40.5 | 65.9 | 67.4 | 74.9 |
| SWE-bench Verified | 42.0 | 49.2 | 54.7 | 63.5 |

The pattern is what you would expect. V4 Flash matches or slightly beats R1 on reasoning while running closer to V3's latency. V4 Pro is a clear step up on every axis, with the SWE-bench number being the headline. 63.5 on SWE-bench Verified puts Pro in striking distance of Claude Sonnet 4 and ahead of every other open model. For an open-weights checkpoint you can host yourself, that is a genuinely new thing.

## When To Pick DeepSeek V4 Over Claude or GPT

This is the question I get most. There is no universal answer, but the heuristics are clearer with V4 than they were with R1.

**Reach for V4 Flash when:** you are running a high-volume workload, the prompts repeat enough to benefit from caching, latency matters more than the last few percent of quality, and your task is bounded enough that a cheap model will not embarrass you. Examples: classification, structured extraction, RAG synthesis over retrieved chunks, first-pass code review, customer support drafting.

**Reach for V4 Pro when:** the task is hard, the failure cost is high, and you want frontier reasoning at a fraction of the closed-model price. Examples: codebase-scale refactors, multi-step agent loops, technical writing where the model has to integrate many sources, math and scientific work, anything that benefits from the 1M context window.

**Stay on Claude when:** you are doing long agentic coding sessions, the work involves Anthropic-specific tooling like Computer Use or the Claude Code SDK, or you need the absolute best result on SWE-bench-style real codebase work. Claude Sonnet 4 still has the edge there, and Opus opens a wider gap.

**Stay on GPT when:** you are deep into the OpenAI ecosystem, using Assistants, the Realtime API, or function calling features that have not been mirrored elsewhere yet, or running on Azure where DeepSeek is not first-class.

**Run V4 locally when:** you have the hardware and the privacy constraint. Flash will fit on a single high-memory workstation at 4-bit quantization. Pro needs a small cluster or a rented H200 box, but the weights are MIT licensed and the inference stack is the same one that already runs V3.

## A Note From The Creator Side

We have been covering DeepSeek on the channel since R1 dropped in January 2025. Every new release has been an excuse to redo the cost math for [DD Empire's](https://devdig.es/) internal tooling, and V4 is the first time the answer has been "move everything." The pricing on Flash makes it the new default for any internal automation that was on `gpt-4o-mini` or `claude-haiku`. The 1M context on Pro means the long-context jobs that previously required Gemini are now back on the table for a single provider.

The honest thing to say is that DeepSeek keeps shipping faster than the closed labs. V3 closed the gap, R1 forced the o1 rewrite, and V4 has reset the price floor for the third time in eighteen months. If your stack is closed-only, your next quarter is going to involve a serious build-vs-buy conversation whether you wanted one or not.

For the four-minute video version of this launch, see [DeepSeek v4 in 4 Minutes](https://youtu.be/Oi6pQmGjH7Y) on the [Developers Digest YouTube channel](https://www.youtube.com/@DevelopersDigest). For the older context, the [DeepSeek R1 and V3 Developer Guide](/blog/deepseek-r1-v3-guide) walks through the architecture and the local deployment story that V4 inherits. For the broader question of where this fits in the 2026 tooling landscape, the [AI Coding Tools Pricing 2026](/blog/ai-coding-tools-pricing-2026) and [Best AI Coding Tools 2026](/blog/best-ai-coding-tools-2026) posts have the comparison tables.

## What To Build This Week

Three concrete things worth a Saturday.

1. **Wire V4 Flash into your existing OpenAI-SDK code as a fallback or A/B variant.** It is one config change. Run it side-by-side for a week and look at the cost and latency deltas on a real workload. The numbers will surprise you.
2. **Try V4 Pro on a task that has been waiting for Claude Opus.** Long codebase refactor, dense research synthesis, anything where context length and reasoning depth both matter. Pro is cheap enough during the launch discount to use it speculatively.
3. **Rebuild one cache-friendly prompt.** Move the stable parts to the top, the variable parts to the bottom, and watch your input bill on Flash drop by an order of magnitude on the cache hit path.

DeepSeek shipped a release that is genuinely worth a workflow change. The next one will probably be along in three months. Build for that.



Extended Thinking in Claude: When Deep Reasoning Pays For Itself
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Extended Thinking Is A Power Tool, Not A Default

Extended thinking is the Claude feature that most teams either ignore or turn on for everything. Both are wrong. It is a budget item - every reasoning token is billed, and a single thinking call can spend 3 to 10x the tokens of a normal completion. Used on the wrong workload, it is a slow, expensive way to get the same answer. Used on the right workload, it is the difference between a model that ships a buggy refactor and one that catches the off-by-one before it merges.

This is the version of the docs I wish I had the first time I plugged thinking into a real product. We will cover what the mode actually does under the hood, the cost-benefit math at the token level, the SDK code you should ship, and the task patterns where the ROI is obvious versus the ones where you are setting cash on fire.

We walked through several live examples in our [Extended Thinking Real-World Examples](https://www.youtube.com/@developersdigest) video on YouTube. This post is the long-form, production-grade companion.

## What Extended Thinking Actually Does

Extended thinking gives Claude a private scratchpad. When you enable it, the model emits a stream of internal `thinking` blocks before it produces the user-visible response. Those blocks are real tokens - they go through the same transformer, they cost real money, and they are returned to you in the API response so you can inspect them. They are not shown to your user unless you choose to surface them.

The mechanism is closer to learned chain-of-thought than to a separate reasoning model. The same Claude model is doing the reasoning; you are just paying for the room to do it. Three things change versus a normal call:

1. **Cost goes up.** Thinking tokens bill at the same rate as output tokens. A task that spends 4k thinking tokens before a 500-token answer [costs](/blog/ai-coding-tools-pricing-comparison) roughly 9x what the bare answer would.
2. **Latency goes up.** Time to first user-visible token is no longer milliseconds; it can be 3 to 15 seconds depending on the budget.
3. **Quality on hard tasks goes up.** Math, multi-step logic, code design, and debugging are dramatically better. Factual lookups and formatting are unchanged.

That last point is the whole game. If your task does not benefit from deliberation, thinking is pure overhead.

## The Cost-Benefit Math, In Real Numbers

Let's put numbers to it. Assume Sonnet [pricing](/blog/ai-coding-tools-pricing-2026) of roughly $3 per million input tokens and $15 per million output tokens, with thinking tokens billed at the output rate.

A typical [RAG](/blog/what-is-rag)-flavored coding-help call:

- Input: 8k tokens (system + tools + retrieved chunks + user message)
- Output: 600 tokens
- Cost without thinking: 8000 x $3/1M + 600 x $15/1M, roughly **$0.033**

Same call with a 4k thinking budget:

- Input: 8k tokens
- Thinking: 4k tokens
- Output: 600 tokens
- Cost with thinking: 8000 x $3/1M + 4600 x $15/1M, roughly **$0.093**

Thinking tripled the bill. That is fine if it caught a bug that would have cost a developer 30 minutes of debugging. It is a disaster if the model was going to give the same answer anyway.

The break-even rule we use:

- **Use thinking** when the cost of a wrong answer is greater than 5x the call cost. Code generation, architecture decisions, debugging, math.
- **Skip thinking** when the cost of a wrong answer is small or easy to detect. Summarization, classification, formatting, factual extraction.
- **Selective thinking** is the production sweet spot: turn it on only for the requests that need it, not for the whole endpoint.

For teams running thousands of these per day, eyeballing this math is not enough. We built [CodeBurn](/blog/codeburn-tui-dashboard-for-claude-code-token-spend) precisely to surface thinking-token spend per route so you can see which prompts are paying for reasoning they don't need.

## The TypeScript Code You Should Actually Ship

Here is a minimal but production-shaped extended-thinking call using the official [Anthropic](/blog/anthropic-vs-openai-developer-experience) SDK. Note the explicit `budget_tokens` and the response handling for thinking blocks.

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

async function deepReason(userQuestion: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 8000,
    thinking: {
      type: "enabled",
      budget_tokens: 4000,
    },
    messages: [
      {
        role: "user",
        content: userQuestion,
      },
    ],
  });

  let thinking = "";
  let answer = "";

  for (const block of response.content) {
    if (block.type === "thinking") {
      thinking += block.thinking;
    } else if (block.type === "text") {
      answer += block.text;
    }
  }

  return {
    thinking,
    answer,
    usage: response.usage,
  };
}
```

A few non-obvious things this code captures:

- `budget_tokens` is a soft cap on the thinking phase. The model can stop sooner if it concludes early. It will not exceed the budget.
- `max_tokens` must be greater than `budget_tokens`. If you set them equal, you get a thinking-only response with no user-visible answer. Yes, people ship this bug.
- The response is multi-block. You must iterate over `content` and dispatch on `block.type`. A single `response.content[0].text` will throw at runtime when thinking is enabled.

## Prompts That Benefit From Thinking, And Prompts That Don't

The biggest mistake is assuming "harder prompt = more thinking helps." That is roughly true, but the shape matters more than the difficulty.

Tasks where thinking dramatically lifts quality:

- **Multi-step reasoning** with intermediate decisions (planning a migration, designing a schema)
- **Adversarial debugging** where the surface symptom is misleading
- **Math and formal logic** where the model needs to track state across steps
- **Code review** of nontrivial diffs where correctness depends on cross-file context
- **Constraint satisfaction** problems (scheduling, resource allocation)

Tasks where thinking is overhead:

- **Lookup and summarization** ("what does this paragraph say")
- **Structured extraction** with a clear schema
- **Format conversion** (markdown to JSON, SQL to ORM)
- **Classification** with well-defined labels
- **Anything you would write a regex for**

A useful heuristic: if you can write a deterministic test that checks the answer in under five lines of code, you probably do not need thinking.

## Combining Thinking With Tool Use

Thinking and tool use are designed to work together, and this is where the real production wins live. The model can reason about which tool to call, call it, see the result inside a thinking block, reason about the result, and call another tool. This is exactly what an agent loop should do.

The mechanics are slightly subtle. When you append a `tool_result` to the conversation and re-invoke the model, the previous thinking block is preserved in the assistant turn. You must include it in the messages array on the next call, or the model loses its reasoning chain. The SDK helpfully returns thinking blocks with a `signature` field; pass them back unchanged.

```typescript
async function agentTurn(messages: Anthropic.MessageParam[]) {
  return client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 8000,
    thinking: { type: "enabled", budget_tokens: 4000 },
    tools: TOOLS,
    messages,
  });
}
```

Strip thinking blocks before showing the conversation to a user. Keep them when you re-invoke the model. Mixing those up is the most common bug we see.

## Production Gotchas Worth Pinning To Your Wall

**1. Thinking tokens count toward your output rate limits.** A 4k thinking budget plus a 1k answer is a 5k output call for rate-limit purposes. Plan capacity accordingly.

**2. Thinking content is not deterministic.** Two calls with the same prompt can produce wildly different reasoning. If you log thinking for debugging, do not assert on it in tests.

**3. You cannot stream a thinking block as plain text.** Streaming returns event types that include `thinking_delta`. If your frontend assumes all deltas are user text, you will leak the model's internal monologue into the UI. Filter on event type.

**4. The 1-hour prompt cache and thinking interact cleanly.** Thinking blocks themselves are not cached, but the input prefix is. A long system prompt plus tool definitions cached, then a thinking call on top, is the cheapest deep-reasoning configuration we have shipped.

**5. Temperature matters less than you think.** People crank temperature up to "encourage creativity" in thinking mode. In our A/B tests, temperature near zero with extended thinking outperforms higher-temperature thinking on every measurable axis except surface variety. Default to 0.

**6. Empty thinking blocks happen.** On easy questions the model sometimes emits a tiny or empty thinking block and then answers. This is normal. You still pay the request overhead but not the budget.

## Selective Thinking: The Production Pattern

The pattern that delivers ROI in real apps is *selective* thinking - a router that decides whether the incoming request deserves reasoning. The cheapest router is a Haiku call with a one-line classifier. The most accurate is a small static heuristic plus a Haiku fallback.

```typescript
async function shouldThink(userInput: string): Promise {
  if (userInput.length < 80) return false;
  if (/^(summarize|format|convert|extract)/i.test(userInput)) return false;

  const classifier = await client.messages.create({
    model: "claude-haiku-4-5",
    max_tokens: 5,
    messages: [
      {
        role: "user",
        content: `Does this request require multi-step reasoning, debugging, or design? Answer "yes" or "no" only.\n\n${userInput}`,
      },
    ],
  });
  const text = classifier.content[0].type === "text" ? classifier.content[0].text : "";
  return /yes/i.test(text);
}
```

In production, this routing pattern typically cuts thinking-token spend by 60 to 80% with zero detectable quality loss on the easy bucket. The classifier costs fractions of a cent. The savings are in dollars per request.

## Monitoring Thinking In Production

Three metrics you should chart from day one:

- **Thinking tokens per request, p50 / p95 / p99.** Spikes are usually a prompt regression that confused the model.
- **Thinking budget utilization.** If p99 hits the budget cap, you are clipping reasoning and probably losing quality.
- **Wrong-answer rate, with vs. without thinking.** This is the only metric that justifies the spend. If it does not move, turn thinking off.

A useful side effect: thinking output is amazing debugging material. When a customer reports a weird answer, the thinking block usually tells you exactly which step the model got wrong. We log it (with PII scrubbing) and review failed requests against it. The [400-Dollar Overnight Bill](/blog/400-dollar-overnight-bill-agent-finops) post-mortem covers the flip side: thinking turned on for the wrong workload, no one watching the meter.

## Production Checklist Before You Ship

- [ ] `budget_tokens` set explicitly, less than `max_tokens`
- [ ] Response parsed by iterating `content` and dispatching on `block.type`
- [ ] Thinking blocks stripped from user-facing UI
- [ ] Thinking blocks preserved when re-invoking with tool results
- [ ] Selective routing in front of any high-traffic endpoint
- [ ] Thinking-token spend tracked per route, alert on anomalies
- [ ] Streaming handlers explicitly filter `thinking_delta` events
- [ ] Temperature set to 0 unless you have an A/B test that justifies otherwise
- [ ] Quality metric (not just cost) tied to the thinking decision

Extended thinking is one of the highest-leverage features in the Claude API on the right workload, and one of the easiest to set fire to your budget on the wrong one. Get the routing right, monitor the spend, and treat the thinking output as the gold mine of debugging data it is.

For more on optimizing Claude in production, see our writeups on [prompt caching](/blog/prompt-caching-claude-api-production-guide) and [tool use patterns](/blog/tool-use-claude-api-production-patterns).



GPT-5.4 for Developers: The Production Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

GPT-5.4 dropped in March 2026 and the noisy headline was "model beats humans on OSWorld." That is true and it is also the least useful thing about the release for anyone shipping software. Two months later, with [GPT-5.5 already on the API](/blog/gpt-5-5-developer-guide) and 5.4 settling into its real role in the lineup, the picture for builders is much clearer than it was on launch day.

This is the developer guide I wanted in March: which workloads actually want 5.4, the SDK code to wire it up, how the 272K-token [pricing](/blog/ai-coding-tools-pricing-2026) cliff bites in practice, and the honest comparison against 5.3 below it and 5.5 above it.

## What 5.4 actually changed at the API layer

There were three substantive changes, and one of them is easy to miss because it lives in the UX layer rather than the API.

Computer use went from "interesting demo" to "thing you can ship." The OSWorld Verified score of 75 percent versus 58.3 percent on 5.3 is not a marginal jump. It moves browser and desktop automation from the territory where you write three retry layers and a human escalation path to the territory where you write one retry layer and a logging path. BrowseComp and WebArena moved together with it, which means the gain is not a single-benchmark artifact.

Context grew to one million tokens with a real cost wrinkle. Anything over 272K tokens is billed at a 2x multiplier on both input and output. The window exists, you can use it, and most workloads should not. More on that under pricing.

Steerable thinking is the part developers undersell. The product UX of redirecting reasoning mid-response shows up in the API as a richer streaming format and a longer effective tool-use loop. If you build with the [Responses API](/blog/openai-responses-api-migration), you can intercept reasoning before the model commits and inject corrections, which is much cheaper than regenerating.

A new [Codex](/blog/openai-codex-guide) fast mode runs roughly 1.5x faster than standard. For batch jobs it is the difference between a one-hour CI lane and a forty-minute one.

## When to reach for 5.4 today

With 5.5 and 5.5 Pro now on the API, 5.4 is no longer the default frontier choice. It is the right call for three specific workloads.

Computer-use and browser-automation agents should still be tested against 5.4 first. Until 5.5's computer-use evals catch up publicly, 5.4's OSWorld lead is the strongest published number on the task. If you are running a [browser agent stack](/blog/best-mcp-servers-2026) where every action is a paid round trip, the higher action accuracy compounds.

Frontend code generation in agentic loops still favours 5.4 in my own evals. Web games, 3D scenes, complex CSS layouts, and React component scaffolds came back with fewer iterations than on 5.3 and roughly tied with 5.5 on first-pass quality, while costing meaningfully less per million tokens.

Long-document workloads up to 272K tokens are 5.4 territory. Below that ceiling the per-token cost is half of 5.5 Pro and the quality gap is small. Cross the cliff and the math flips immediately.

For everything else, including most agentic terminal coding and long-horizon task graphs, [5.5 or 5.5 Pro](/blog/gpt-5-5-developer-guide) is the better default. And for high-volume utility work that does not need reasoning at all, neither model is the right tool.

## Wiring up GPT-5.4 with the OpenAI SDK

The model IDs that ship are `gpt-5.4` for the standard variant and `gpt-5.4-thinking` for the reasoning variant. Both work through the Responses API, which is what I use for anything that touches tools.

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    input="Summarize this changelog and flag breaking changes.",
    instructions="You are a release-notes auditor. Be terse.",
    max_output_tokens=2000,
)

print(response.output_text)
```

For the thinking variant you opt into reasoning effort explicitly. The API exposes the same `reasoning.effort` knob as 5.3 and the new `effort_budget` cap that was introduced alongside 5.4.

```python
response = client.responses.create(
    model="gpt-5.4-thinking",
    input=user_query,
    reasoning={"effort": "high", "effort_budget": 8000},
    max_output_tokens=4000,
    stream=True,
)

for event in response:
    if event.type == "response.reasoning.delta":
        # Surface reasoning to the user in real time so they can steer.
        ui.append_reasoning(event.delta)
    elif event.type == "response.output_text.delta":
        ui.append_answer(event.delta)
```

`effort_budget` is a hard ceiling on reasoning tokens. It is the single most useful knob for keeping thinking-model [costs](/blog/ai-coding-tools-pricing-comparison) bounded in production. Set it once per call site, treat it as a budget, and alert when you hit it.

## Computer use with the built-in tool

The shipped computer-use tool is the cleanest way to use 5.4 for browser and desktop automation. Pair it with a sandboxed browser session and you get a tight loop.

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.4",
    tools=[{
        "type": "computer_use_preview",
        "display_width": 1280,
        "display_height": 800,
        "environment": "browser",
    }],
    input=[{
        "role": "user",
        "content": [
            {"type": "input_text", "text": "Find the pricing page on stripe.com and extract the per-transaction fee."},
            {"type": "input_image", "image_url": initial_screenshot_data_url},
        ],
    }],
    truncation="auto",
)

for action in response.output:
    if action.type == "computer_call":
        result = sandbox.execute(action.action)
        # Feed the resulting screenshot back as the next input item.
```

Two things matter for production. First, always pass `truncation="auto"` once your action history grows, otherwise long sessions will overflow even the million-token window. Second, instrument every `computer_call` with a step counter and a timeout. Models that score 75 percent on OSWorld still fail 25 percent of the time, and the failure mode is usually a loop, not a clean error.

## The 272K pricing cliff is real

The pricing snapshot at launch, which is still the published rate as of this writing:

```
gpt-5.4
  Input:           $2.50  / 1M tokens
  Output:          $10.00 / 1M tokens
  Cached input:    $0.25  / 1M tokens
  Above 272K ctx:  2x multiplier on input and output

gpt-5.4-thinking
  Input:           $5.00  / 1M tokens
  Output:          $20.00 / 1M tokens
  Cached input:    $0.50  / 1M tokens
  Above 272K ctx:  2x multiplier on input and output
```

The 2x cliff above 272K tokens is the line item that gets every team that does not measure. A single in-context-RAG call on a large monorepo can sit at 290K tokens. Run that a thousand times a day on the thinking variant and you are paying like you ran a 5.5 Pro workload, except on the older model.

Two practical rules. Cache aggressively on the system-prompt and tool-spec prefix; the 10x cached-input discount turns most agent loops into a different cost curve. And put a hard guard at 270K tokens with a fallback path that either truncates older turns or fans out to multiple parallel calls under the cliff. Both are cheap to implement once and pay forever.

If you have not built cost telemetry yet, see the [Cost Tape](/blog/skillforge-ci-and-cost-tape) approach we use across the DD app stack. It is the smallest viable telemetry layer that catches this kind of regression before the bill arrives.

## Benchmarks against 5.3 and 5.5

The numbers below are a mix of published OpenAI evals and my own runs on the same agent suite I use across model upgrades. The 5.5 column reflects 5.5 Pro on default reasoning settings.

| Benchmark                  | GPT-5.3 | GPT-5.4 | GPT-5.5 Pro |
|----------------------------|---------|---------|-------------|
| OSWorld Verified           | 58.3%   | 75.0%   | 78.1%       |
| BrowseComp                 | 49.7%   | 71.2%   | 73.8%       |
| WebArena                   | 51.2%   | 68.4%   | 70.9%       |
| SWE-bench Verified         | 69.2%   | 74.1%   | 79.4%       |
| Frontend (internal eval)   | 62%     | 81%     | 82%         |
| 240K-token doc QA          | 64%     | 71%     | 84%         |

Two observations matter for a build decision. Computer use saturates fast above 5.4. The jump from 5.3 to 5.4 is roughly 17 points; from 5.4 to 5.5 Pro it is 3 points. If your workload lives there, 5.4 is most of the way to the frontier at half the price. Long-context comprehension is where 5.5 Pro pulls cleanly ahead. If you regularly cross 200K tokens of meaningful content, the answer-accuracy delta is too large to ignore.

## A real migration path from 5.3 to 5.4

The honest playbook for a team still on 5.3 in late April 2026 looks like this.

Run your existing eval suite against 5.4 before changing a line of production code. If you do not have an eval suite, see the [Agent Eval Bench](/blog/ai-agent-frameworks-compared) writeup; the cheapest version is a hundred prompts with golden outputs and a regression diff.

Migrate computer-use and frontend agents to 5.4 first. These are the workloads with the biggest verified gains and the lowest blast radius if something regresses.

Hold long-document workloads on whatever they run today until you have measured 5.4 against 5.5 Pro on the same documents. Anything that crosses 272K should probably skip 5.4 entirely and go straight to 5.5 Pro to avoid the cliff.

Set `effort_budget` on every thinking-model call site. The single biggest production cost surprise on the thinking variants is unbounded reasoning on tasks the model finds confusing.

Ship the 270K-token guard. Even if you never expect to hit it, one rogue retrieval upstream will, and you want a fallback path, not a 2x bill.

## Caching, prompt structure, and the things that actually move the bill

Three implementation choices end up dominating GPT-5.4 production cost more than the model variant itself.

The first is system-prompt caching. The Responses API caches the static prefix of your input, including the system instructions and tool specifications, at a 10x discount. If your agent hits the same model with a 4K-token tool spec a hundred times an hour, the difference between cached and uncached input is the difference between a serious line item and a rounding error. Structure your prompts so the static part is genuinely static, and put any per-call variability at the end.

The second is reasoning effort. The thinking variant defaults to `medium`, and `medium` will quietly burn through reasoning tokens on prompts the model finds ambiguous. Force `low` for routine work, reserve `high` for the tasks that actually need it, and always pair `high` with an `effort_budget` ceiling. In one DD-app migration I cut the monthly thinking-model bill by 38 percent without a measurable quality drop simply by reclassifying which call sites needed which effort tier.

The third is image inputs in computer-use loops. Each screenshot you feed back as `input_image` is billed by image tokens, and a long agent session can accumulate dozens. Downsample screenshots to the minimum resolution the model still acts reliably on, which in my testing is `1024x768` for most browser tasks. Going from full 1440p screenshots to 1024x768 cut my computer-use bill nearly in half with no measurable accuracy loss.

## Developer commentary, two months in

I have shipped on 5.4 across half the [DD app portfolio](/blog/agentic-dev-stack-2026) and the lived-in verdict is narrower than the launch coverage suggested. It is the strongest computer-use model that has shipped to date by a comfortable margin. It is a clear upgrade for frontend code generation in agentic loops. It is a pricing win below 272K tokens.

It is not a replacement for [Codex with 5.3](/blog/gpt-5-codex) on tight low-latency code edits, where the older model still has a speed and cost edge. It is not the right pick over 5.5 Pro for long-context document work. And it is comprehensively beaten on agentic terminal coding by the current Anthropic frontier, which I covered in the [OpenAI versus Anthropic 2026](/blog/openai-vs-anthropic-2026) writeup.

What 5.4 changed permanently is the assumption that browser automation is a research problem. It is now an engineering problem with a model that hits the accuracy bar. The implementation work is on us.

## Watch the 10-minute breakdown

If you want the visual walkthrough that pairs with this guide, the [GPT-5.4 in 10 Minutes](https://youtube.com/watch?v=MwATr76kFXs) DevDigest video covers the launch announcement, the steerable thinking UX, and the live coding demos that motivated several of the recommendations above.



GPT-5.5-Codex in Production: What Actually Changes
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT
I migrated three production [coding agents](/blog/what-is-an-ai-coding-agent-2026) from `gpt-5-codex` to `gpt-5.5-codex` over a single weekend. One was a multi-file refactor bot that runs against a 400k LOC monorepo. One was a PR triage agent that comments on every pull request before a human looks at it. The third was an internal CLI that scaffolds boilerplate from JIRA tickets.

What follows is the real diff: token cost, p95 latency, PR acceptance rate, and the four prompt scaffolds I kept versus the ones I had to throw away. If you are sitting on the fence about migrating, this is the writeup I wish I had on Friday night.

## The Unification Thesis

The headline is not the version bump. The headline is that OpenAI has merged its two parallel post-training stacks into one. For most of 2025, `gpt-5-codex` and `gpt-5` were trained for different optimization targets. Codex variants were tuned for long-horizon, tool-using, file-editing workflows. The base GPT-5 line was tuned for reasoning, instruction following, and general chat.

For model-selection context, compare this with [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

`gpt-5.5-codex` is the first model that inherits both. The instruction-following work that landed in 5.5 base shows up in the Codex variant immediately, and the multi-file editing behavior that Codex pioneered now informs how the base model handles code. In practice this means fewer surprises when you mix prompt patterns from your chat stack with patterns from your agent stack.

For builders this matters because it lowers the cost of standardizing on one model across product surfaces. I now run the same model behind my CLI, my PR bot, and my customer-facing chat features. One eval suite, one cost line, one prompt library.

## Migration Mechanics

The model string change itself is trivial. The OpenAI Python SDK migration was three lines per agent.

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5-codex",
    input=[
        {"role": "developer", "content": "You are a senior backend engineer reviewing pull requests for a Next.js monorepo. You always cite file paths and line numbers."},
        {"role": "user", "content": "Review the diff in pr_12894.patch and flag any issues with auth, database queries, or type safety."},
    ],
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
    reasoning={"effort": "medium"},
)

print(response.output_text)
```

Two things to watch when migrating. First, any code that pinned `reasoning.effort` to `high` for `gpt-5-codex` should drop to `medium` first and benchmark. The 5.5 model is more efficient at the same effort level, and several of my agents got better outputs at lower effort, not higher. Second, deprecated parameters from older Codex preview models such as `max_completion_tokens` should be replaced with `max_output_tokens` in the [Responses API](/blog/openai-responses-api-migration). The SDK will warn, not error, so it is easy to miss.

The system-prompt rewrites that paid off were small but consistent. I removed the explicit "think step by step" scaffolding that I had baked into `gpt-5-codex` prompts. In 5.5 it is redundant and occasionally produces verbose preambles that you then have to strip in post. I also tightened my output-format instructions, because the new model follows JSON schemas and structured-output requests with noticeably less drift.

If you keep prompts in version control, and you should, now is the time to tag the pre-migration prompt set. We use [Promptlock](https://github.com/developersdigest/promptlock) to version prompts across model migrations exactly so the rollback is one command, not a git archaeology session. The diff between my `gpt-5-codex` and `gpt-5.5-codex` prompt branches is genuinely useful as a reference.

## Benchmarks From My Own Agents

These numbers are from production traffic over a 7 day window before and after migration. Same prompts where I did not change them, same tools, same eval set. Token counts are summed across input plus output.

| Agent | Tokens before | Tokens after | p95 before | p95 after | PR accept before | PR accept after |
|---|---|---|---|---|---|---|
| Refactor bot | 41.2M | 33.8M | 18.4s | 14.1s | 61% | 72% |
| PR triage | 12.6M | 11.9M | 6.2s | 5.0s | n/a | n/a |
| Boilerplate CLI | 3.9M | 3.4M | 9.8s | 7.6s | 88% | 91% |

A few honest caveats. The refactor bot saw the biggest gain because it benefits most from longer-horizon planning, which is where 5.5 made the cleanest jump. The PR triage agent was already cheap and fast, so the absolute delta is small. The boilerplate CLI is so structured that the model improvements are almost noise. The win there is consistency, not capability.

I track all of this from my status bar with [Cost Tape](https://github.com/developersdigest/cost-tape), which broke the migration cost delta out per agent in real time. Watching the line chart drop on the refactor bot for three straight days was the moment I committed to rolling out fully.

## What 5.5 Finally Gets Right

Multi-file edits are the thing I want to talk about first, because this was the longest standing pain point with the 5-codex line. The previous model would correctly identify that a refactor required changes in five files, then make the edits inconsistently, sometimes naming a renamed function correctly in three places and using the old name in the other two. 5.5 holds the rename across the entire edit batch with much higher reliability. My refactor bot now lands cross-file renames on the first try in roughly four out of five attempts, up from about half.

Long-horizon tasks are the second improvement. Tasks that span more than 20 tool calls used to drift. The model would forget early constraints, contradict its own plan, or revisit the same file three times. 5.5 holds the plan better. I am no longer adding "remember the original requirement" reminders into my system prompts every five turns.

Instruction following on ambiguous tickets is the third. JIRA tickets are a hazard surface for any coding agent because they are written by humans who already share context with the reader. 5.5 asks fewer clarifying questions and makes better default assumptions when the ticket is underspecified. When my boilerplate CLI sees a ticket like "add the new endpoint for the marketing team", the model now correctly infers the file layout, the route convention, and the test pattern from the rest of the repo without me having to spell it out in the system prompt.

For a side-by-side terminal recording of the same multi-file refactor task running on `gpt-5-codex` and `gpt-5.5-codex`, the [DevDigest YouTube hands-on video](https://www.youtube.com/@DevelopersDigest) is worth ten minutes of your time. Watching the two agents run on a split screen tells you more than any benchmark table.

## Where It Still Fumbles

I want to be honest about the failure modes because the rollout-everything-on-Monday energy on Twitter does not match my experience.

Config drift is the first real bug class. When a repo has both a `pnpm-workspace.yaml` and a stale `lerna.json`, 5.5 will sometimes follow the lerna config and produce commands that no longer apply. The fix is the same as it was on the previous model: tell the agent which config file is canonical in the developer message, and verify before letting it run scripts.

Confidently wrong refactors are the second. The model is now better at multi-file edits, which paradoxically makes it more dangerous when it is wrong. A confident sweep across 12 files with a subtly incorrect type signature is harder to catch in review than a hesitant attempt at three files. The countermeasure is unchanged: run the test suite before accepting, and make your CI block on failures.

Cost cliffs on long contexts are the third. Pricing on 5.5-codex scales with input tokens as expected, but the model is more willing to read entire files end to end when it could have grepped. If you give it filesystem tools without rate limits, you will see your bill jump on agents that previously were cautious. I added a hard cap on file reads per task in my agent loop and the daily spend dropped back into expected territory.

## Verdict and Prompt Patterns I Am Keeping

Verdict: migrate. The latency win alone justifies the move for any user-facing agent. The cost delta is real if your traffic skews toward refactor-style work. The risk of confidently-wrong sweeps is manageable with discipline you should already have.

Four prompt scaffolds survived migration intact and I will keep using them across whatever ships next.

The first is the role-with-codebase-anchor pattern. State the role, name the codebase, and pin one or two architectural facts the model needs to behave correctly. This worked on `gpt-5-codex` and works equally well on 5.5.

The second is the cite-file-and-line discipline. Always require the model to cite the exact file path and line number when making claims about code. This kills hallucinated references on any model and is even cheaper to enforce on 5.5 because the model resists drifting from the requirement.

The third is the plan-then-execute split. Have the model emit a plan first, log it, then execute against the plan. The plan is invaluable for postmortems when an agent goes wrong, and 5.5 produces visibly better plans than its predecessor.

The fourth is the structured-output-or-fail rule. If a downstream consumer expects JSON, declare the schema and reject anything that does not match. The 5.5 model is forgiving enough that this rarely triggers, but the contract has saved me twice this month already.

If you are mid-migration, the playbook is straightforward. Tag your prompt set, swap the model string, drop reasoning effort one level, run your eval suite, watch your cost dashboard for 48 hours, and only then roll out broadly. The unified stack is real, the gains are real, and the only thing left is the discipline of measuring it on your own traffic instead of trusting any benchmark, including the table I wrote above.



GPT-5.5 for Developers: A Production Field Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

GPT-5.5 and GPT-5.5 Pro landed on the API on April 24. I rebuilt three production agents on 5.5 Pro the same day. One got noticeably better, one regressed in a way I did not see coming, and one I had to tear out and replace with a cheaper model because the new [pricing](/blog/ai-coding-tools-pricing-2026) curve made it economically pointless.

This is the field guide I wish I had that morning. It covers what the model actually does differently in API terms, which tier matches which workload, the agentic improvements I can verify with my own evals, the regression nobody is writing about, and the migration playbook I now run on every codebase that touches the OpenAI SDK.

## What "smartest and most intuitive" actually means in API terms

OpenAI's launch post leans on words like "intuitive" and "agentic," which is fine for marketing copy but does not help you decide whether to flip the env flag. In API terms, here is what changed.

For model-selection context, compare this with [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

The default reasoning depth is higher. GPT-5.5 ships with a recalibrated `reasoning.effort` scale where the new `medium` is closer to what `high` was in 5.4. That means a naive drop-in replacement using the same parameters will cost more and run slower out of the box, even before you change a line of code.

Tool-call dispatch is more conservative. In my eval suite, 5.5 emits roughly 18 percent fewer speculative tool calls on tasks where multiple tools could plausibly answer. It waits for more context before committing. That is excellent for production agents that pay per tool round trip and a slight regression for chat-style assistants where the perceived snappiness comes from immediate action.

Long-context handling is genuinely better. The same 240K-token document QA task that gave 5.4 a 71 percent answer-accuracy in my bench now scores 84 percent on 5.5 Pro. The improvement concentrates in the middle third of the context window, which is exactly where 5.4 had its known sag.

Pricing rebalanced. Input tokens on 5.5 are slightly cheaper than 5.4. Output tokens are slightly more expensive. 5.5 Pro is roughly 4x the cost of 5.5. For agents that emit short tool calls and consume long context, 5.5 is a free win. For agents that generate long-form output, you may end up paying more.

## 5.5 vs 5.5 Pro: which tier for which workload

I keep this matrix taped to the wall above my desk. The rule of thumb is that 5.5 is the new default and 5.5 Pro earns its keep only on a narrow band of workloads.

```ts
import OpenAI from "openai";

const client = new OpenAI();

// Default tier: chat, summarization, structured extraction, simple agents
const fast = await client.responses.create({
  model: "gpt-5.5",
  input: userMessage,
  reasoning: { effort: "low" },
});

// Pro tier: long-horizon agents, multi-document synthesis, hard reasoning
const heavy = await client.responses.create({
  model: "gpt-5.5-pro",
  input: planningPrompt,
  reasoning: { effort: "medium" },
  tools: agentTools,
});
```

Use 5.5 for anything user-facing that needs a sub-2-second time-to-first-token. Use 5.5 Pro when the cost of being wrong is higher than the marginal token bill. Concretely, that means [coding agents](/blog/what-is-an-ai-coding-agent-2026) that touch shared infra, financial extraction where a misread number costs money, and any agent that runs unattended for more than a few minutes.

If you are running mixed-model agents, lean on a router. I push every request through a tiny wrapper that picks the model based on a `complexity` score I attach to the task at queue time. The router lives behind the same OpenAI SDK call surface, which means swapping models is a one-line config change.

## Agentic improvements I can verify

I ran [Agent Eval Bench](https://github.com/developersdigest/agent-eval-bench) against 5.4, 5.5, and 5.5 Pro the day the API opened. The bench has 280 deterministic agentic tasks across coding, document workflows, and tool-use chains. Here is what came out.

Tool-call accuracy on the 80-task tool-use suite climbed from 78 percent on 5.4 to 89 percent on 5.5 and 91 percent on 5.5 Pro. The improvement is concentrated in tasks that require choosing between two semantically similar tools. 5.5 picks the right one more often, which means fewer wasted round trips and shorter end-to-end latencies in production despite the slower per-call thinking time.

Long-horizon planning held up. On the 40-task multi-step planning suite, 5.5 Pro completed 34 of 40 without human intervention, compared to 27 of 40 for 5.4. The failures clustered around tasks where the agent had to abandon a partially-completed plan and restart, which is the same weak spot 5.4 had. Progress, but not a solved problem.

Document workflows improved more than I expected. Extracting structured data from messy PDFs, the kind of task that used to require Pro-tier and high effort to get right, now works reliably on 5.5 with `effort: "low"`. That is a real cost saving. I cut my document pipeline bill by 38 percent the week after migrating.

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",
    input=[
        {"role": "system", "content": "Extract invoice line items as JSON."},
        {"role": "user", "content": [{"type": "input_file", "file_id": file_id}]},
    ],
    reasoning={"effort": "low"},
    response_format={"type": "json_schema", "json_schema": invoice_schema},
)
```

The same call on 5.4 needed `effort: "high"` to hit acceptable accuracy on my golden set. That is the kind of quiet improvement that does not make the launch post but moves real money.

## The regression nobody is talking about

Here is the part I have not seen anyone else write up. On creative-writing-style tasks where the model has to maintain a consistent voice across a long generation, 5.5 hallucinates voice drift more often than 5.4 did. My voice-consistency eval, which is a 40-prompt suite that scores style adherence across 4000-token continuations, dropped from 82 percent on 5.4 to 71 percent on 5.5. 5.5 Pro recovers most of the gap, hitting 79 percent, but it is still a regression.

The drift looks like the model getting bored with the established voice partway through and reverting to a more neutral, technical register. My theory is that the conservative tool-call dispatch and the recalibrated reasoning effort interact badly with creative continuations, but I cannot prove it from outside the model.

If you have agents that depend on consistent persona output, run your own eval before flipping the flag. I had to keep one of my agents on 5.4 because the regression was material to its product feel. OpenAI has not deprecated 5.4 yet, so this is a viable holdout for a while longer.

## Migration playbook

Here is the playbook I now run on every codebase. It takes a couple of hours per service and has caught real problems on every migration so far.

Step one, pin the old model behind a flag. Before you change any prompt code, wrap the model name in an env-driven config. This is the rollback lever you will be glad to have.

```ts
const MODEL = process.env.OPENAI_MODEL ?? "gpt-5.4";

const response = await client.responses.create({
  model: MODEL,
  input: prompt,
});
```

Step two, run an eval harness against both models on a representative sample of real production traffic. Do not trust internal benchmarks. Capture 200 real requests, replay them against 5.4 and 5.5, and score the outputs on whatever metric matters for your product. This is exactly what Agent Eval Bench is built for, but a 50-line script will do.

Step three, watch the cost curve. [Cost Tape](https://github.com/developersdigest/cost-tape) gives me a live spend graph across mixed-model rollouts. The first week of any migration is when surprise bills happen, usually because the new default reasoning effort is higher and you forgot to set `effort: "low"` on a high-volume endpoint.

Step four, ramp by traffic share. I move new requests to the new model in 5 percent increments over a week, watching error rates and customer-reported quality at each step. If the eval lied, I find out before the bill does.

Step five, plan the rollback. Keep the old model live for at least two billing cycles. The regression I described above caught me on day six of a rollout, which would have been a bad time to discover I had ripped out the old code path.

## Prompt patterns I'm rewriting

Two prompt patterns earned an immediate rewrite for 5.5.

First, drop the "think step by step" preamble. 5.5 thinks more deeply by default, and the explicit instruction now adds latency without improving accuracy on my evals. On the math reasoning suite, removing the preamble cut average response time by 410ms with no measurable accuracy change.

Second, tighten tool descriptions. Because 5.5 is more conservative about tool dispatch, ambiguous tool descriptions now translate to the model giving up and asking the user instead of trying. Rewrite each tool description to specify exactly what inputs it expects and what outputs it produces, in the second person, with concrete examples.

```ts
// Before
const searchTool = {
  type: "function",
  name: "search_docs",
  description: "Searches documentation.",
  parameters: { /* ... */ },
};

// After
const searchTool = {
  type: "function",
  name: "search_docs",
  description: "Use this when the user asks how to do something with our SDK. Input is a natural-language query string. Output is up to 5 documentation snippets with URLs. Prefer this over guessing API details from training data.",
  parameters: { /* ... */ },
};
```

The diff is small. The behavioral change is large. My agent's tool-use rate on documentation questions went from 64 percent to 91 percent after rewriting the descriptions in this style, with no model or prompt change beyond the tool spec.

## Where I landed

GPT-5.5 is the new default. 5.5 Pro is the right answer when correctness [costs](/blog/ai-coding-tools-pricing-comparison) more than tokens. The day-one migration is straightforward if you have an eval harness and a kill switch, painful if you do not. The voice-drift regression is real and worth testing for if your product depends on persona consistency.

I shipped the eval bench results, the cost-tape dashboard, and the day-one review on the [DevDigest YouTube channel](https://www.youtube.com/@DevelopersDigest) the same week the API opened. If you are migrating, start with the eval harness. Everything else falls out of having ground truth.

## Frequently Asked Questions

### What is GPT-5.5 and how does it differ from GPT-5.4?

GPT-5.5 is OpenAI's April 2026 model release that ships with a recalibrated reasoning scale where the default depth is higher than 5.4. It has better long-context handling (84% accuracy vs 71% on 240K-token document QA), more conservative tool-call dispatch (18% fewer speculative calls), and rebalanced pricing with cheaper input tokens but more expensive output tokens. The model comes in two tiers: GPT-5.5 for everyday work and GPT-5.5 Pro for complex reasoning tasks.

### When should I use GPT-5.5 vs GPT-5.5 Pro?

Use GPT-5.5 for user-facing work that needs sub-2-second time-to-first-token: chat, summarization, structured extraction, and simple agents. Use GPT-5.5 Pro when the cost of being wrong exceeds the token bill: coding agents touching shared infrastructure, financial extraction where misread numbers cost money, and any agent running unattended for more than a few minutes. Pro is roughly 4x the cost of 5.5, so the extra reasoning power has to justify the spend.

### How does GPT-5.5 pricing compare to previous models?

Input tokens on GPT-5.5 are slightly cheaper than 5.4. Output tokens are slightly more expensive. GPT-5.5 Pro is roughly 4x the cost of 5.5. For agents that emit short tool calls and consume long context, 5.5 is a free win. For agents that generate long-form output, you may pay more. Document extraction workflows that previously required Pro-tier with high effort now work reliably on 5.5 with low effort, cutting costs by 30-40%.

### Is GPT-5.5 better for AI coding agents?

Yes, with caveats. Tool-call accuracy improved from 78% on 5.4 to 89% on 5.5 and 91% on 5.5 Pro, with gains concentrated in choosing between semantically similar tools. Long-horizon planning improved from 27/40 to 34/40 task completions without human intervention. The more conservative tool dispatch means fewer wasted round trips, but chat-style assistants may feel slower because the model waits for more context before acting.

### Are there any regressions in GPT-5.5 I should know about?

Yes. Voice consistency on creative writing tasks dropped from 82% on 5.4 to 71% on 5.5. The model tends to drift toward a neutral, technical register partway through long generations. GPT-5.5 Pro recovers most of the gap (79%), but if your product depends on consistent persona output, test before migrating. OpenAI has not deprecated 5.4 yet, so you can hold out on affected agents.

### Do I need to change my prompts for GPT-5.5?

Two patterns need rewrites. First, drop "think step by step" preambles - 5.5 reasons more deeply by default, and the explicit instruction now adds latency without improving accuracy. Second, tighten tool descriptions to specify exact inputs, outputs, and when to use each tool. Ambiguous tool descriptions cause 5.5 to ask clarifying questions instead of trying, which breaks agents that expect immediate tool use.

### What is the safest way to migrate to GPT-5.5?

Five steps: (1) Pin the old model behind an env flag for rollback. (2) Run an eval harness against both models on 200 real production requests. (3) Watch the cost curve - surprise bills happen because the new default reasoning effort is higher. (4) Ramp by traffic share in 5% increments over a week. (5) Keep the old model live for at least two billing cycles. Regressions can surface on day six of a rollout.

### How does GPT-5.5 handle long context compared to older models?

Significantly better. The same 240K-token document QA task that gave 5.4 a 71% answer-accuracy scores 84% on 5.5 Pro. The improvement concentrates in the middle third of the context window, exactly where 5.4 had its known accuracy sag. Document extraction tasks that required Pro-tier with high effort on 5.4 now work reliably on 5.5 with low effort.



DeepSeek R1, PPO, and GRPO Explained for Devs
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Why GRPO is suddenly everywhere

Six months ago, if you asked an ML engineer how reasoning models were trained, the answer involved PPO, a reward model, a value head, and a lot of careful KL constraints. Today, half the open-weights reasoning models on Hugging Face mention GRPO in their model card, and the other half are racing to switch. [DeepSeek](/blog/deepseek-v4-developer-guide) R1 was the inflection point. Its training recipe leaned on Group Relative Policy Optimization, the results spoke loudly, and the rest of the field followed.

For model-selection context, compare this with [Claude vs GPT for Coding: Which Model Writes Better TypeScript?](/blog/claude-vs-gpt-coding) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

If you are a developer who builds with LLMs but has never trained one, the alphabet soup is intimidating. PPO. GRPO. DPO. RLHF. RLAIF. Reward models, value heads, advantage estimates, clip ratios. Most explanations assume two semesters of RL background you do not have. This post is the version that does not.

The goal here is a working mental model. Not a derivation, not a proof, not a reproduction of the math. By the end you should be able to read the DeepSeek R1 paper, understand the [Hugging Face GRPO writeup](https://huggingface.co/blog/NormalUhr/grpo) it leans on, and have an opinion about why this recipe is winning.

## The setup: what RL on LLMs is actually trying to do

Start from a base model. It has been pretrained on the internet and then supervised-fine-tuned on instruction data. It can answer questions. It is not particularly good at reasoning, math, or following complex constraints. You want to make it better at those things.

You have a way to score answers. Maybe it is a learned reward model trained on human preference data. Maybe it is a programmatic checker, like running a math problem through SymPy or executing generated code against unit tests. Either way, given a prompt and a model output, you can produce a number that says "this answer was good" or "this answer was bad."

Now you want to nudge the model so that it produces more of the high-scoring answers and fewer of the low-scoring ones. That is the entire game. Every method on the menu, PPO, GRPO, DPO, REINFORCE, is a different answer to one question: how do you turn a reward signal into a gradient update without the model collapsing?

## PPO in one paragraph

Proximal Policy Optimization, the original RLHF workhorse, looks like this. You generate an answer. You score it. You also run a separate value model that predicts, for any partial sequence, what the eventual reward will probably be. The difference between the actual reward and the predicted reward is the advantage, the surprise factor. You take a gradient step that pushes the model to produce more answers that beat the value model's prediction and fewer that fall short. You add a KL penalty against the original base model so the policy does not drift into nonsense, and you clip the gradient ratio so a single big update cannot destabilize training.

The conceptual cost of PPO is the value model. It is roughly the same size as the policy. You have to train it, store it, run it on every step, and tune it. RLHF infrastructure is dominated by the bookkeeping around this second model.

```python
# Pseudocode, PPO step
prompts = sample_batch()
responses = policy.generate(prompts)
rewards = reward_model(prompts, responses)
values = value_model(prompts, responses)  # the expensive part
advantages = rewards - values
loss = ppo_clip(policy.logprobs(responses), old_logprobs, advantages)
loss += beta * kl_divergence(policy, reference_policy)
loss.backward()
```

That value model is what GRPO removes.

## GRPO in one paragraph

Group Relative Policy Optimization makes a clever swap. Instead of training a value model to predict expected reward, it samples a group of responses for each prompt, scores them all, and uses the group's mean and standard deviation as the baseline. The advantage of any response is just how much better or worse it scored than its peers from the same prompt. No value model needed.

```python
# Pseudocode, GRPO step
prompts = sample_batch()
groups = [policy.generate(p, n=8) for p in prompts]  # 8 responses per prompt
rewards = [[reward_model(p, r) for r in group] for p, group in zip(prompts, groups)]

# advantage = (reward - group_mean) / group_std
advantages = [(r - mean(group_r)) / std(group_r) for r, group_r in zip(rewards, rewards)]

loss = ppo_clip(policy.logprobs(responses), old_logprobs, advantages)
loss += beta * kl_divergence(policy, reference_policy)
loss.backward()
```

The change is small, the consequences are large. You eliminated the value model. Your training infrastructure is half the size. Your reward signal is denser per prompt, because you are computing eight rewards where PPO computed one. And empirically, on math and code reasoning benchmarks, the recipe just works.

## Why this matters for DeepSeek R1

DeepSeek R1's training recipe is the highest-profile validation of GRPO to date. The team did not need a learned reward model. The reasoning tasks they cared about, math problems and code, have programmatic verifiers. A math answer is right or wrong. Code passes the tests or it does not. That gives you a deterministic, free, infinitely scalable reward signal.

Combine that with GRPO's no-value-model property, and the entire training stack collapses to: a policy model, a reference model for the KL term, and a verifier function. You can run that on commodity training infrastructure. You do not need to train and serve a separate reward network. You do not need preference annotation pipelines. The cost structure changes from "RLHF needs a research lab" to "RL post-training needs a verifier and a GPU cluster."

R1's other contribution was showing that you can do a lot of GRPO before the model breaks. The training run was long. The reward signal was simple. The model learned to produce long chain-of-thought reasoning traces because longer correct traces won relative to shorter wrong ones in the group comparison, and the group baseline kept that signal stable.

## The dev's mental model, in three rules

Strip the math out and the recipe becomes simple enough to remember.

**Rule one: rewards drive direction.** Whatever you reward more, you get more of. If your verifier rewards correct final answers regardless of reasoning, you get a model that gets answers right with terse reasoning. If you reward longer reasoning that ends in correct answers, you get a chain-of-thought model. The reward function is the product spec.

**Rule two: a baseline keeps the gradient sane.** The model needs to know what counts as "better than expected." PPO uses a value model to estimate that. GRPO uses peer responses. Either way, you are subtracting a baseline so that the gradient signal is the surprise, not the absolute reward. Without a baseline, training is noisy and unstable.

**Rule three: a leash keeps the model honest.** The KL term against a reference model is what stops the policy from drifting into reward hacks. If you remove the leash, the model finds adversarial outputs that score high on the reward function but are nonsense. The leash is non-negotiable.

That is GRPO. Sample a group, compute advantages relative to the group, take a clipped gradient step, keep a leash. The rest is engineering.

## Hands-on: minimal GRPO with TRL

Hugging Face's TRL library shipped GRPO support shortly after the DeepSeek R1 paper landed. A minimal training script looks like this:

```python
from trl import GRPOConfig, GRPOTrainer
from datasets import load_dataset

dataset = load_dataset("openai/gsm8k", "main", split="train")

def reward_correctness(prompts, completions, **kwargs):
    rewards = []
    for prompt, completion in zip(prompts, completions):
        gold = extract_answer(prompt["answer"])
        predicted = extract_answer(completion)
        rewards.append(1.0 if predicted == gold else 0.0)
    return rewards

config = GRPOConfig(
    output_dir="grpo-r1-replication",
    num_generations=8,         # group size
    max_completion_length=2048,
    learning_rate=5e-6,
    beta=0.04,                 # KL coefficient
    per_device_train_batch_size=1,
    gradient_accumulation_steps=8,
)

trainer = GRPOTrainer(
    model="meta-llama/Llama-3.1-8B-Instruct",
    reward_funcs=[reward_correctness],
    args=config,
    train_dataset=dataset,
)
trainer.train()
```

A few things worth flagging when you actually run this.

The group size matters. Eight is a reasonable default. Smaller groups give noisier baselines. Larger groups burn more compute per step and the marginal benefit drops. The DeepSeek paper used larger groups, but they had the budget.

The KL coefficient matters. Too low, the model wanders. Too high, the model cannot learn anything new. 0.04 is a common starting point for instruction-tuned bases. Tune it.

Reward functions can be lists. TRL accepts multiple reward functions and sums them. That is how you do "correctness plus formatting" or "correctness plus length penalty" without rewriting the whole pipeline.

For the full reproduction walkthrough with a working dataset and evaluation harness, the [DevDigest YouTube channel](https://youtube.com/@DevelopersDigest) has the video version, and the [DD Academy](https://academy.developersdigest.tech) hosts the full course on RL post-training.

## Where this fits the agent stack

GRPO is most relevant for one specific use case: you have a domain where you can write a verifier, and you want a model that gets noticeably better at that domain than the base. Code generation. Math. Tool calling with strict schemas. Structured extraction. Anything that has a checker.

It is less relevant for open-ended chat where the only reward signal is human preference. There, DPO and its variants are still simpler to run than GRPO, because they sidestep the rollout step entirely.

For agent builders, the most interesting application is fine-tuning a small open-weights model on a verifiable agent task. Think: a 7B model that learns to call a specific tool API correctly, judged by whether the API call succeeds and returns the expected shape. GRPO on that setup is cheap, the verifier is free, and the resulting model is small enough to deploy on commodity inference hardware.

We use this kind of pipeline internally on [AgentFS](https://agentfs.developersdigest.tech) for the agent-side filesystem operations. The verifier is whether the operation succeeded against a reference virtual filesystem. The training run is small. The deployed model is tiny. The behavior is rock solid because the verifier is deterministic.

## What to watch next

Three threads worth following.

**Process reward models.** GRPO uses a final-answer reward. Process reward models score every reasoning step. The combination, GRPO with a process reward, is the next obvious move and several labs are working on it.

**Verifier-free GRPO.** The recipe assumes a verifier. The interesting research direction is whether learned reward models that judge reasoning quality can substitute for programmatic verifiers without the usual reward-hacking failure modes.

**Smaller-model viability.** Most GRPO results are at 7B and up. The question is how small you can go before the recipe stops working. There is a real prize at 1B to 3B for on-device reasoning models if the answer is "small enough."

If you take one thing away: GRPO is PPO minus the value model, with a group baseline filling the gap. That is the whole trick. Now go read the R1 paper without flinching.



mlinter: Hugging Face's New Linter for Transformers Modeling Files
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The void in ML code quality, finally filled

For years, ML code has lived in a strange parallel universe where the rest of software engineering looked on with quiet horror. Python services had ruff, mypy, black, isort, pylint, bandit. Frontend had eslint, prettier, biome, and a half-dozen plugin ecosystems on top. Even shell scripts had shellcheck. But transformers modeling files? You opened a `modeling_*.py` in a Hugging Face repo and stared at hundreds of lines of attention math, custom forward methods, copy-pasted block patterns, and TODO comments that had survived three model releases.

For model-selection context, compare this with [Claude vs GPT for Coding: Which Model Writes Better TypeScript?](/blog/claude-vs-gpt-coding) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

Linters did not understand the conventions. Type checkers gave up at the first `Optional[Tuple[torch.FloatTensor]]` return type. Reviewers signed off on PRs because the tests passed and they trusted the author. The result was a slow accumulation of small bugs, inconsistent dtype handling, masked-attention edge cases, and divergence between model variants that were supposed to share a base implementation.

[Hugging Face just shipped mlinter](https://huggingface.co/blog/huggingface/mlinter), and it is the first credible attempt to drag transformers code into the same CI hygiene that the rest of the industry treats as table stakes. If you maintain a model implementation, fine-tune custom architectures, or ship agents on top of HF transformers, this tool belongs in your pipeline.

## What mlinter actually does

mlinter is a static analyzer purpose-built for the modeling file conventions inside the transformers library. It is not a generic Python linter. It encodes the patterns that the HF maintainers have spent years enforcing in code review and turns them into machine-checkable rules.

The rule set covers the things that matter:

- **Copy-paste lineage.** Transformers uses `# Copied from` comments to signal that a method was lifted from another model and should stay in sync. mlinter verifies the lineage is intact, the function signatures match, and any drift is flagged as a violation rather than silently rotting.
- **Attention patterns.** Mask handling, dtype upcasting around softmax, scaling factors, and rotary embedding application all have correct and incorrect ways to be written. mlinter knows the canonical shape and warns when a custom implementation deviates.
- **Init and config wiring.** Models that forget to register a parameter, miss a config flag, or shadow a base class attribute now fail the lint pass instead of failing at training time three weeks later.
- **Dead code and unreachable branches.** The transformers codebase has accumulated a lot of `if self.something_legacy:` paths. mlinter helps surface what is still load-bearing versus what can be deleted.

The big idea is conventional checking, not generic checking. mlinter is opinionated in the same way that the transformers code review process is opinionated, which is exactly what makes it useful.

## Installing and running it locally

Setup is intentionally boring, which is the right call for a CI tool. You install it like any other Python dev dependency:

```bash
pip install mlinter
```

Run it against a single modeling file or a directory of them:

```bash
mlinter src/transformers/models/llama/modeling_llama.py
mlinter src/my_model/
```

Output is the standard lint format: file, line, rule code, and a human-readable explanation. If you have used ruff or flake8, the ergonomics will feel immediately familiar.

A minimal example. Suppose you have a custom model that copied attention from [Llama](/blog/llama-4-developers-guide) but forgot to keep the `# Copied from` marker honest after refactoring the scaling factor:

```python
# Copied from transformers.models.llama.modeling_llama.LlamaAttention.forward
def forward(self, hidden_states, attention_mask=None, position_ids=None):
    bsz, q_len, _ = hidden_states.size()
    # ... your code drifts here
    attn_weights = torch.matmul(q, k.transpose(2, 3))  # missing scaling
    attn_weights = nn.functional.softmax(attn_weights, dim=-1)
    return self.o_proj(torch.matmul(attn_weights, v))
```

mlinter catches this, prints the diff between the claimed source and the actual implementation, and tells you either to remove the `# Copied from` marker or restore the scaling. That is a class of bug that ate hours of debugging time before anyone wrote it down as a rule.

## Wiring it into CI

This is where the value compounds. A linter you remember to run is a linter that does not catch anything. The point is to put it on the wall.

GitHub Actions, the most common path:

```yaml
name: lint
on:
  pull_request:
    paths:
      - "**/modeling_*.py"
      - "**/configuration_*.py"

jobs:
  mlinter:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install mlinter
      - run: mlinter src/
```

Pre-commit, for the local layer:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/huggingface/mlinter
    rev: v0.1.0
    hooks:
      - id: mlinter
        files: ^.*modeling_.*\.py$
```

Run `pre-commit install` once per clone and the hook fires on every commit touching a modeling file. The combination of pre-commit at the developer layer and CI at the merge layer means you do not waste reviewer attention on the same five issues every PR.

## Where it fits the agent stack

This is where opinionated commentary matters. mlinter is not a tool for application developers wiring up an agent that calls a hosted Claude or [Gemini](/blog/gemini-deep-research) API. If your stack stops at `client.messages.create(...)`, you do not need it.

mlinter is a tool for the layer underneath: teams that ship custom model code, fine-tune open-weights models with non-trivial architecture changes, or maintain in-house forks of transformers for inference serving. That is a smaller audience than the generic agent dev population, but it is a critical one. Every team that has tried to fork a HuggingFace model to add flash attention, change RoPE base, or splice in a custom embedding layer has hit the silent-drift problem that mlinter solves.

The honest comparison is to ruff. ruff did not invent linting. It invented a fast, batteries-included, opinionated linter that made the existing best practices easy to adopt. mlinter is doing the same job for a narrower domain. The marginal cost of adding it to a repo is essentially zero. The marginal benefit is one less class of subtle correctness bug shipping into production weights.

For deeper pattern walkthroughs and full transformers fork case studies, the [DevDigest YouTube channel](https://youtube.com/@DevelopersDigest) has the visual versions of the workflows discussed here.

## Wiring it into a real ML observability product

The natural pairing for mlinter is anything that observes model behavior in production, because the linter catches the static class of issues and the observability stack catches the dynamic class. We use [Traces](https://traces.developersdigest.tech) for the runtime side. mlinter goes on the static side of the same pipeline.

The flow looks like this:

1. Developer pushes to a feature branch.
2. Pre-commit runs mlinter, blocks the commit if a `# Copied from` lineage is broken.
3. CI runs mlinter on the diff plus the full test suite.
4. PR merges. Build artifact deploys to a staging inference server.
5. Traces captures token-level behavior, attention entropy, and latency distribution on a synthetic eval set.
6. Anomaly on the runtime side gets correlated back to the static diff that caused it.

That feedback loop is the point. Static analysis without runtime observability gives you false confidence. Runtime observability without static analysis gives you mystery bugs. Both together collapse the time from "something looks off" to "here is the line that did it."

If you are bootstrapping a new model repo from scratch and want the standard layout already wired, the [DD template](https://template.developersdigest.tech) ships mlinter, ruff, mypy, and a Traces hook in the default scaffold.

## What to watch next

Three open questions worth tracking over the next quarter.

**Rule expansion velocity.** mlinter shipped with a focused initial rule set. The interesting question is how fast HF expands it to cover quantization patterns, LoRA adapter wiring, and multi-modal model conventions. If the rule cadence stays high, this becomes the de facto checker for the entire HF ecosystem within a year. If it stalls at v0.1, it stays niche.

**Third-party rule plugins.** ruff got powerful when the plugin ecosystem hit critical mass. mlinter has not announced a plugin API, but the demand is obvious. Anyone running a custom inference stack has internal conventions they would love to encode as lint rules.

**Editor integrations.** Linting at CI time is good. Linting in the editor as you type is better. An LSP-shaped surface for mlinter, hooked into [Cursor](/blog/what-is-cursor-ai-code-editor-2026), Zed, and VS Code, would change the daily experience of writing modeling code. Watch for that.

In the meantime, install it, wire it into your pipeline, and stop relying on reviewer attention to catch the same five issues. That alone is worth the afternoon it takes to set up.



KV Caching: A Practical Guide to Optimizing Transformer Inference
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The wall every local-LLM dev hits

You spin up a 7B model on a decent GPU. The first generation feels fast. Then you push the context to a few thousand tokens and the throughput collapses. You profile and the answer is the same one a thousand devs have arrived at independently: most of your forward passes are recomputing attention over tokens you already saw.

For model-selection context, compare this with [AI Design Slop: 15 Patterns That Out Your App as Vibe-Coded](/blog/ai-design-slop-and-how-to-spot-it) and [Create Beautiful UI with Claude Code: The Style Guide Method](/blog/create-beautiful-ui-claude-code); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

This is the KV-cache wall. It is the canonical bottleneck of transformer inference, the first real performance lesson when you stop calling hosted APIs and start running models yourself, and the topic of one of the clearest explainers Hugging Face has shipped this year - [not-lain's KV caching post](https://huggingface.co/blog/not-lain/kv-caching).

This piece is the developer's version of that explainer. Less math, more code, more focus on the engineering decisions you actually make when you ship.

## What KV caching actually is

A transformer generates one token at a time. Each new token attends to every previous token in the sequence. If your context is one thousand tokens and you generate the one-thousand-and-first, the model needs the keys and values for all one thousand previous tokens to compute attention.

The naive implementation recomputes those keys and values on every generation step. You feed the whole sequence through the model again, throw away most of the output, and keep only the new token. This is `O(n^2)` work to generate `n` tokens.

The KV cache is the obvious fix. After the first forward pass, you have computed the keys and values for the prompt. Cache them in memory. On the next step, you only run the new token through the model, attend it against the cached keys and values, and produce one new pair of cached entries. The whole generation becomes `O(n)` instead of `O(n^2)`.

The speedup is enormous. For a sequence length of 2,048 with a 7B model, KV caching can take you from "this is unusable" to "this is real-time" on the same GPU.

## What it looks like in code

If you are using Hugging Face Transformers, KV caching is on by default in `generate()`. The interesting work happens when you build your own inference loop and need to reason about it directly.

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "meta-llama/Llama-3.2-3B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="cuda",
)

prompt = "The KV cache stores"
input_ids = tokenizer(prompt, return_tensors="pt").input_ids.cuda()

past_key_values = None
generated = input_ids
max_new = 50

with torch.no_grad():
    for _ in range(max_new):
        if past_key_values is None:
            inputs = generated
        else:
            inputs = generated[:, -1:]

        out = model(
            input_ids=inputs,
            past_key_values=past_key_values,
            use_cache=True,
        )
        past_key_values = out.past_key_values
        next_token = out.logits[:, -1, :].argmax(dim=-1, keepdim=True)
        generated = torch.cat([generated, next_token], dim=1)

print(tokenizer.decode(generated[0]))
```

The shape of the cache is what matters. `past_key_values` is a tuple with one entry per transformer layer. Each entry holds two tensors - the keys and the values - of shape `[batch, num_heads, seq_len, head_dim]`. The `seq_len` dimension grows by one with every generation step.

That growing dimension is the catch. The cache scales linearly with sequence length, and the constant is not small. For a 7B-class model with 32 layers, 32 heads, head_dim 128, in float16, the math is:

```
2 * 32 layers * 32 heads * 128 head_dim * 2 bytes = ~512 KB per token
```

At 2,048 tokens of context, that is one gigabyte of KV cache per request. At 32K context, sixteen gigabytes. The KV cache, not the model weights, is what fills your VRAM in long-context inference.

## The memory tradeoffs that matter

Once you internalize that the KV cache is most of your memory budget, a lot of optimization decisions snap into focus.

Quantization of the cache itself. You can store the cache in int8 or int4 instead of bfloat16. The accuracy hit is usually small for chat workloads. Hugging Face Transformers supports int8 cache out of the box - flip a config flag, halve your memory.

Multi-query and grouped-query attention. Modern model architectures - [Llama](/blog/llama-4-developers-guide) 3, Mistral, Qwen - share key and value heads across multiple query heads. Grouped-query attention with eight kv heads instead of thirty-two cuts the cache by 4x with minimal quality cost. This is why a 70B Llama 3 has roughly the same KV-cache footprint per token as a 7B from a couple of years ago.

Paged attention. The vLLM project's contribution. Instead of allocating one contiguous KV cache buffer per request, vLLM allocates fixed-size pages and looks them up by a virtual address per request. This eliminates the fragmentation that wastes memory in batched serving and is the single biggest reason vLLM dominates self-hosted inference today. If you are serving more than one request at a time, you should not be writing your own attention loop - you should be running vLLM or a successor.

Sliding window attention. Some architectures attend only over a window of recent tokens. The KV cache becomes a fixed-size ring buffer instead of a growing array. Mistral popularized this. The cost is that the model genuinely cannot see beyond the window, so anything that depends on long-range structure has to be summarized into recent tokens.

The KV cache discard problem. For very long contexts, the cache may not fit even with quantization. You then have to choose what to evict. Options range from naive (drop the oldest tokens), to clever (the H2O paper, attention-score-based eviction), to extreme (re-summarize the dropped region into a much shorter prefix). Production systems usually pick a static policy - keep the system prompt, keep the last N turns - and call it good.

## Gotchas worth knowing

Cache reuse across requests is real and underused. If many requests share a long system prompt, you can compute the cache for the system prompt once and reuse it across all requests. This is the prefix caching feature in vLLM and SGLang. For agent workloads with a long system prompt and short user turns, prefix caching can halve your cost per request.

Batch size and cache size are linked. The KV cache is per-request. If you serve eight requests at once, you have eight caches in memory. The maximum batch size is bounded by `(VRAM - model_weights) / (cache_per_token * max_seq_len)`. Profile this before you size your hardware.

Speculative decoding interacts in non-obvious ways. With a draft model proposing tokens that the target model verifies, you have two caches running in lockstep, and rolling back the target cache when the draft is wrong is fiddly. Most frameworks handle this for you. If you implement it yourself, double-check the rollback path.

Streaming output and the cache. The cache is mutated in place by `generate()`. If you stream tokens to a client and the client disconnects, you need to release the cache memory promptly. Plumbing the cancel path through your inference server is a real source of memory leaks.

## DD take: where this fits the agent stack

The honest perspective from someone who has shipped a few agent products. KV caching is not a feature you turn on - it is the air everything else breathes. Every other inference optimization assumes it. Continuous batching, speculative decoding, prefix caching, paged attention - all of them are reorganizations of the KV cache.

For most application devs, the right move is not to write your own KV-cache logic. The right move is to pick a serving framework that has solved it and to understand the framework's trade space. vLLM is the default for self-hosted Llama-class models. SGLang is the more aggressive option for very long contexts and structured generation. TensorRT-LLM is the right answer if you live on NVIDIA hardware and need every last token per second.

The case for understanding KV caching deeply is when you start doing things the framework was not designed for. Long-context retrieval pipelines where you want to splice in cached prefixes per query. Multi-tenant agent serving where you want to share cache across users with the same system prompt. Local on-device inference where the cache is the dominant memory cost and you cannot afford a generic policy.

If you are running models locally, even casually, the rule of thumb is: most of your VRAM is going to be cache, not weights, and the choice of architecture matters more than the choice of model size for inference economics.

## Wiring it into a real product

We have been profiling KV-cache behavior inside [Traces](https://traces.developersdigest.tech), our agent-run timeline tool. Traces was originally built to render Claude Code transcripts as a stepped UI. Adding self-hosted-model traces meant we had to surface KV-cache utilization as a first-class metric, because for self-hosted runs the cache is the most predictive number for "is this run going to OOM."

The pattern that has worked is to log, per turn, the prefix cache hit ratio, the live cache size in MB, and the maximum-allowed cache size for the request. Plot those over the run and you can immediately see when a request is cache-bound versus compute-bound versus prompt-bound. This kind of observability has been hard to get out of self-hosted serving frameworks; building it in turned out to be a small but valuable feature.

For workloads that need persistent agent state, [AgentFS](https://agentfs.developersdigest.tech) is where the prefix-cache idea pays off. AgentFS gives agents a durable workspace across runs, and most of what an agent does in a given session involves the same long system prompt, the same toolset descriptions, and the same workspace summary. Caching the prefix once per agent and reusing it across turns inside a session is the difference between five-second latency and one-second latency on a self-hosted setup. The same idea generalizes to any product with a stable long prefix.

## What to watch next

The interesting open questions.

Cache compression beyond int8. Recent research is pushing into 4-bit and even 2-bit cache quantization with minimal quality cost. If those numbers hold up in production, the effective memory budget for long-context inference doubles or quadruples without new hardware.

Cache-aware routing. Multi-tenant inference systems are starting to route requests to the GPU that already has a relevant prefix cached. The economic logic is obvious. The implementation is gnarly because you need a global view of which caches live where.

KV-cache sharing across models. If you have a chain of models - a small fast model proposing, a large slow model verifying, a re-ranker checking - sharing the KV computation across them is an open research direction. The constraint is that the architectures have to match.

Hardware support. The newest accelerators are starting to ship with KV-cache-specific memory hierarchies - dedicated cache-only HBM stacks, faster cache-to-compute paths. The hardware is racing to catch up to the access pattern that transformer inference actually exhibits, and the next generation of GPUs will have very different KV-cache economics from the current one.

We are running [a deeper hands-on walkthrough on YouTube](https://youtube.com/@DevelopersDigest) - building a tiny inference loop with explicit KV cache management, then bolting on prefix caching, then comparing against vLLM. Watching the mental model assemble in code is, in our experience, the fastest way to actually internalize this. Once you have built it once, you stop being surprised by inference performance forever.



Mercury 2 Developer Guide: Building With a Diffusion LLM in Production
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Why This Guide Exists

The [Mercury 2 announcement post](/blog/mercury-2-diffusion-llm) covered what the model is and why diffusion language models matter. This post is for the developer who already gets the pitch and wants to know what it actually feels like to build with one. We will wire up the API, run a real agent loop, talk about the trade-offs nobody tweets about, and figure out where Mercury 2 belongs in your stack and where it does not.

If you have not read the [primer on diffusion language models](/blog/diffusion-language-models), the short version is this. Every other LLM you use generates one token at a time, locking each token before moving on. Mercury 2 does not. It generates multiple tokens per forward pass and refines the output across iterations, the same coarse-to-fine process that powers image and video diffusion. That single design choice is why it clears 1,000 tokens per second on standard hardware while staying competitive on reasoning benchmarks.

## The Numbers That Matter for Production

Before any code, here is what shapes the build decisions:

- Throughput: over 1,000 tokens per second, compared to roughly 89 t/s for Claude Haiku 4.5 and 71 t/s for GPT-5 Mini.
- Quality: ties GPT-5 Mini on AIME 2025 at 91.1, scores competitively on GPQA and LiveCodeBench.
- Pricing: $0.25 per million input tokens, $0.75 per million output tokens.
- Context window: 128,000 tokens.
- Features: [tool use](/blog/tool-use-claude-api-production-patterns), structured outputs, RAG, OpenAI-compatible API.
- Reasoning levels: instant, low, medium, high.

That last point is the one most teams miss. Mercury 2 lets you pick how hard the model thinks per request. You do not have to commit to a single reasoning budget for your whole app the way you do with most reasoning models.

## Wiring Up the API

The API is [OpenAI](/blog/openai-vs-anthropic-2026)-compatible. If your app already talks to OpenAI, the migration is three changes: base URL, model string, API key.

Here is a minimal Python call using the OpenAI SDK:

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["INCEPTION_API_KEY"],
    base_url="https://api.inceptionlabs.ai/v1",
)

response = client.chat.completions.create(
    model="mercury-2",
    messages=[
        {"role": "system", "content": "You answer concisely."},
        {"role": "user", "content": "Explain diffusion sampling in two sentences."},
    ],
    extra_body={"reasoning_effort": "low"},
)

print(response.choices[0].message.content)
```

The same shape in TypeScript with the Vercel AI SDK, which is what the demo in [the original video](https://youtube.com/watch?v=quOe8V2n9rU) uses:

```ts
import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const inception = createOpenAI({
  apiKey: process.env.INCEPTION_API_KEY,
  baseURL: "https://api.inceptionlabs.ai/v1",
});

const { text } = await generateText({
  model: inception("mercury-2"),
  prompt: "Summarize the difference between diffusion and autoregressive LLMs.",
});

console.log(text);
```

That is the entire onboarding cost. No new SDK, no new auth pattern, no rewriting your retry logic. If you have already built an [agent on top of Anthropic, OpenAI, or DeepSeek](/blog/ai-agent-frameworks-compared), you can swap Mercury 2 in behind a config flag.

## Tool Use Without Wrapper Hell

Tool use is where Mercury 2 starts to feel different in production. Tool calls are where autoregressive models eat your latency budget alive. Each call generates a JSON payload sequentially. Each round trip waits on token-by-token output before the orchestration layer can fire the actual tool. In a five-step agent loop you pay that latency tax five times.

Diffusion generation collapses that tax. Here is a tool definition the way the video demo uses it, with a browser tool that scrapes Hacker News:

```python
tools = [{
    "type": "function",
    "function": {
        "name": "open_url",
        "description": "Open a URL and return the page text.",
        "parameters": {
            "type": "object",
            "properties": {
                "url": {"type": "string"},
            },
            "required": ["url"],
        },
    },
}]

response = client.chat.completions.create(
    model="mercury-2",
    messages=[
        {"role": "user", "content": "Find the top three AI stories on Hacker News and summarize the comments."},
    ],
    tools=tools,
    extra_body={"reasoning_effort": "medium"},
)

for call in response.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)
```

In a tool-heavy agent the wall clock time on Mercury 2 lands somewhere between five and ten times faster than a comparable autoregressive model running the same loop. That is not a benchmark gain, that is a UX gain.

## Structured Outputs

Diffusion is a natural fit for structured generation because the model refines the entire output at once instead of committing left to right. Schema adherence stops feeling like a fight with the sampler.

```python
schema = {
    "name": "extract_post",
    "schema": {
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "url": {"type": "string"},
            "comment_count": {"type": "integer"},
            "summary": {"type": "string"},
        },
        "required": ["title", "url", "comment_count", "summary"],
    },
}

response = client.chat.completions.create(
    model="mercury-2",
    messages=[{"role": "user", "content": page_text}],
    response_format={"type": "json_schema", "json_schema": schema},
)
```

The schema returns clean on the first pass at "low" reasoning effort for most extraction tasks. That is the use case I would migrate first if you are running a high-volume scraping or normalization pipeline.

## Choosing a Reasoning Level

Mercury 2 exposes four levels through the `reasoning_effort` parameter: instant, low, medium, high. Treat them like a knob between latency and quality, not a quality dial alone.

A working rule from a few weeks of building with it:

- instant: classification, routing, intent detection, autocomplete-style suggestions, anything where you would have used a 7B chat model.
- low: schema extraction, summarization, single-tool calls, [RAG](/blog/what-is-rag) answer generation against a clean retrieval set.
- medium: multi-tool agent loops, RAG over messy retrieval, code edits across one or two files, planning steps.
- high: math, deep code reasoning, agent loops with conditional branching, anything where you would have reached for an o-series model or a Claude Sonnet thinking variant.

The key insight is that you can mix them in a single user-facing flow. Use instant for the planner, medium for the executor, low for the formatter. Most of your latency budget gets spent where reasoning actually matters.

## Where Mercury 2 Beats Autoregressive

The honest answer is, anywhere latency multiplies.

- Voice agents. The P95 of voice UX is brutal. Sub-second total turn time is table stakes, and most autoregressive reasoning models cannot get there. Mercury 2 can do tool-augmented turns inside that budget at low or medium reasoning.
- Coding iteration. Tight feedback loops where you prompt, review, tweak. The diff between a 1,000 t/s edit and an 80 t/s edit changes how you work. It moves you from "wait for the model" to "thinking with the model".
- High-fanout pipelines. Document processing, classification, normalization. If you are paying for a million extractions a day, Mercury 2 at $0.25 input and $0.75 output is hard to beat, and the speed cuts your worker count.
- Real-time UIs that need streaming structured data. Forms that fill themselves, dashboards that explain themselves, anything where the user is staring at the screen waiting for JSON.

## Where I Would Not Reach for It Yet

A few honest caveats from time in the trenches:

- Long-form creative writing where you want a specific voice. Autoregressive models still feel more natural in pure prose generation. This is shifting, but it is real today.
- Agentic workflows where the model needs to commit early and never revisit. Diffusion's strength is revision. If your task is more "stream of consciousness" than "draft and refine", you will not see the same lift.
- Anything that depends on a specific frontier model's quirks. If your prompts are tuned to Claude's RLHF flavor or GPT-5's instruction following, plan to retune. Mercury 2 follows instructions cleanly but it is its own model.

## Diffusion vs Autoregressive: The Mental Model

The framing that finally clicked for me. Autoregressive generation is a typewriter. Each keystroke is permanent. If the model commits to a wrong token early, the rest of the output has to work around that mistake. That is where reasoning models burn tokens correcting themselves mid-stream.

Diffusion generation is an editor with a draft. The model produces a rough version of the entire output, then refines it across iterations. Mistakes get caught and fixed during generation, not after. That is why diffusion and reasoning compose so naturally. The reasoning step is not bolted on, it is part of the sampling loop.

This is the same architectural shift that took image generation from GANs to Stable Diffusion. The people who built those original diffusion methods, including Stefano Ermon at Stanford, are the people who founded Inception Labs. Mercury 2 is them applying the same playbook to text.

## Migration Checklist

If you want to A/B Mercury 2 against your current model, here is the shortest path I have found:

1. Add an environment variable for `INCEPTION_API_KEY` and a feature flag for the model selection.
2. Swap the base URL and model string behind that flag. Keep your existing prompt and tool definitions.
3. Start at `reasoning_effort: "low"` and only step up if you see quality regressions.
4. Measure two things in parallel: P50 wall clock latency end-to-end, and your existing quality eval if you have one.
5. For agent loops, log per-step latency. The wins are usually concentrated in the tool-call rounds, not the final answer.
6. If you are running streaming UIs, make sure your frontend can actually keep up. I have seen apps where the model finishes before the React render loop catches up. Real problem to have.

The whole switch is a half-day of work for most apps. The decision after that is a quality call against your own evals.

## Final Read

Mercury 2 is the first model that makes me think the autoregressive monoculture has a real challenger, not just a faster sibling. The benchmarks land in the right zip code. The price is aggressive. The OpenAI compatibility kills the integration cost. And the reasoning-level knob means you do not have to pick a single point on the latency-quality curve for your whole app.

I would not throw out my Sonnet or GPT-5 calls today. I would route every latency-sensitive path through Mercury 2 and start measuring. That is where the wins live, and that is where the architecture actually pays off.

If you want the original deep dive, the [Mercury 2 video walkthrough](https://youtube.com/watch?v=quOe8V2n9rU) on the channel covers the demo and the diffusion explainer. If you want the broader context on agent frameworks, the [agent frameworks comparison](/blog/ai-agent-frameworks-compared) is the right next read.



Model Context Protocol: A Production Guide To Building MCP Servers
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Beyond The Marketing: What MCP Actually Solves

The [Model Context Protocol](/blog/what-is-mcp) is the bit of plumbing that turns Claude from "an LLM with tools you wrote inline" into "an LLM that can talk to any system on your network through a standardized contract." That sentence sounds like it could be a press release, so here is the engineering version: MCP is a JSON-RPC-over-stdio (or SSE, or HTTP) protocol that lets a client  -  Claude Desktop, Claude Code, the Agent SDK, or your own  -  connect to a server that exposes *resources* (data Claude can read) and *tools* (actions Claude can take), with capability negotiation, structured errors, and persistence.

The reason it matters: you can write a tool layer once and reuse it across every Claude surface and, increasingly, across other agents. The reason most teams misuse it: they build an [MCP server](/blog/complete-guide-mcp-servers) when they should have shipped inline tool use, or vice versa.

We did the [MCP Deep Dive: Building Extensible Agents](https://www.youtube.com/@developersdigest) video on the channel walking through a live MCP build. This is the production-grade companion. We build a real server, debug it, talk about transports, and cover the spec gaps you will hit the first week in production.

## MCP vs Inline Tool Use

A short heuristic before we go deeper, because this is the question I get most often:

- **Inline tool use:** small number of tools, tightly coupled to the agent, no reuse across surfaces, no persistence. Ship the tools as code in your agent process.
- **MCP server:** tools belong to a *system* (database, internal API, dev environment). Multiple agents or surfaces will use them. There is state worth persisting between calls. Long-running processes are involved.

Building an MCP server for a three-tool weather agent is overkill. Building inline tool use to expose your entire production database to [Claude Code](/blog/what-is-claude-code-complete-guide-2026) is going to be unmaintainable. Pick the right layer.

For a deeper look at when each pays off, the [MCP vs function calling](/blog/mcp-vs-function-calling) post covers the trade-offs and the [DD MCP Lens debugger](/blog/mcp-debugging-with-mcp-lens) shows the kind of tooling you will eventually want when you are running real MCP servers.

## Architecture In Practice

The protocol has three pieces:

1. **Client**  -  Claude Desktop, Claude Code, your custom app via the [Anthropic](/blog/anthropic-vs-openai-developer-experience) SDK's MCP integration.
2. **Transport**  -  `stdio` for local processes, `streamable HTTP` (formerly SSE) for remote servers.
3. **Server**  -  your code. Exposes resources, tools, and prompts.

Capability negotiation happens during the `initialize` handshake. The client says what it supports; the server says what it offers. Both sides know what is on the table before any real work starts. This is what lets the protocol evolve without breaking older clients.

Two distinctions worth burning in:

- **Resource vs Tool.** Resources are *read-only data sources* with URIs (`postgres://customers/123`). Tools are *actions* (`run_migration`, `send_email`). Use resources for "let Claude read this," use tools for "let Claude do this." Mixing them up is the most common architectural mistake in early MCP servers.
- **stdio vs HTTP.** Stdio is for local-only servers Claude Desktop launches as subprocesses. HTTP is for remote servers shared across users or machines. Stdio is simpler, has zero auth concerns, and starts/stops with the client. HTTP is what you ship for anything multi-user or persistent.

## Building Your First MCP Server In TypeScript

The official `@modelcontextprotocol/sdk` is the path of least resistance for a real server. Here is a minimal Postgres-backed server exposing customer rows as resources and a `query_revenue` tool. It is short, but every piece is the production shape.

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ListToolsRequestSchema,
  ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import { Pool } from "pg";
import { z } from "zod";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const server = new Server(
  { name: "acme-customers", version: "0.1.0" },
  { capabilities: { resources: {}, tools: {} } }
);

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  const { rows } = await pool.query(
    "SELECT id, name FROM customers ORDER BY name LIMIT 100"
  );
  return {
    resources: rows.map((r) => ({
      uri: `postgres://customers/${r.id}`,
      name: r.name,
      mimeType: "application/json",
    })),
  };
});

server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
  const id = req.params.uri.replace("postgres://customers/", "");
  const { rows } = await pool.query("SELECT * FROM customers WHERE id = $1", [id]);
  if (!rows.length) throw new Error(`Customer ${id} not found`);
  return {
    contents: [
      {
        uri: req.params.uri,
        mimeType: "application/json",
        text: JSON.stringify(rows[0], null, 2),
      },
    ],
  };
});

const QueryRevenueInput = z.object({
  customer_id: z.string(),
  start_date: z.string(),
  end_date: z.string(),
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "query_revenue",
      description:
        "Sum revenue for a customer between two ISO dates (inclusive). Returns USD cents.",
      inputSchema: {
        type: "object",
        properties: {
          customer_id: { type: "string" },
          start_date: { type: "string", description: "YYYY-MM-DD" },
          end_date: { type: "string", description: "YYYY-MM-DD" },
        },
        required: ["customer_id", "start_date", "end_date"],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (req) => {
  if (req.params.name !== "query_revenue") {
    throw new Error(`Unknown tool: ${req.params.name}`);
  }
  const input = QueryRevenueInput.parse(req.params.arguments);
  const { rows } = await pool.query(
    `SELECT COALESCE(SUM(amount_cents), 0) AS total
     FROM invoices
     WHERE customer_id = $1 AND invoice_date BETWEEN $2 AND $3`,
    [input.customer_id, input.start_date, input.end_date]
  );
  return {
    content: [{ type: "text", text: JSON.stringify({ total_cents: rows[0].total }) }],
  };
});

const transport = new StdioServerTransport();
await server.connect(transport);
```

Wire this up in `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "acme-customers": {
      "command": "node",
      "args": ["/abs/path/to/dist/server.js"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}
```

Restart Claude Desktop, and the customers list shows up as resources, the tool shows up in the tool palette. That is the basic shape. Everything from here is making it production-ready.

## Real-World Integration Patterns

Three patterns we have shipped variations of:

**Private data access.** The example above. Database rows, internal API responses, file system contents  -  anything the model should be able to read without you exporting it. The key design choice: expose row-level resources, not schemas. Let Claude pull only what it needs, not the whole table.

**Multi-service orchestration.** A single MCP server that fronts five internal microservices. Tools become the public API of your platform, not the public API of each service. This is where MCP shines for internal devtools  -  you ship one server, expose curated actions, and every Claude surface in the company can use it.

**Long-running processes.** Tools that kick off background jobs and return a job ID, paired with a resource that exposes the job status. This is where MCP beats inline tool use cleanly: the model can poll the resource until the job finishes, and the server holds the state.

Things to handle in production:

- **Timeouts.** Default Claude client timeouts are tight. Long-running tools should return job IDs immediately and stream status via a resource, not block.
- **Retries.** The protocol does not retry. If a tool call fails, the model decides whether to retry. Make your error messages actionable.
- **Versioning.** Bump the server `version` field and add new tools alongside old ones. Do not silently change tool semantics  -  clients cache schemas.

## Debugging And Observability

The MCP Inspector is the first tool to reach for. Run it against your server before you ever connect Claude:

```bash
npx @modelcontextprotocol/inspector node dist/server.js
```

It opens a UI showing the protocol handshake, lists your resources and tools, and lets you invoke them with arbitrary inputs. Half the bugs we hit in early MCP servers are visible in the inspector before they are visible in Claude.

Beyond the inspector, three production must-haves:

1. **Structured logs on every request.** `tool_name`, `duration_ms`, `ok`, `error`. Stdio servers should log to stderr  -  Claude Desktop captures it.
2. **Health probes for HTTP servers.** Plain `GET /health` returning 200. Cheap insurance.
3. **Replay capture.** Log the exact JSON-RPC request and response for every call. When something goes wrong, you can replay it offline against the inspector.

Common issues we see, in rough frequency order:

- **Schema mismatches.** The model sends a parameter shape your handler does not accept. Almost always because the description is ambiguous. Tighten with enums and required fields, same as inline tools.
- **Timeouts.** A query takes 30 seconds, the client gives up at 10. Decompose into job + status pattern.
- **Auth failures on remote servers.** Bearer tokens expire, refresh logic is missing. Build refresh into the transport layer, not the handler.
- **Stale tool lists in the client.** Some clients cache `tools/list` aggressively. Restart the client after schema changes during dev.

## Scaling Beyond One Server

Once you have more than one MCP server, things to watch:

**Tool name collisions.** Two servers exposing `search` will confuse the client. Namespace by server (`acme-customers__query_revenue`)  -  most clients do this automatically, but some do not. Check your client's behavior.

**Load balancing.** For HTTP servers, run multiple instances behind a load balancer. JSON-RPC requests are mostly stateless. Where you have state (subscriptions, long-running jobs), pin sessions or move state to a shared store.

**Auth.** stdio inherits the user's local trust. HTTP servers need real auth. The current dominant pattern is OAuth 2.1 with the client doing a browser-based flow on first connect. The MCP spec has a section on this; follow it, do not roll your own.

**Rate limiting.** Per-tool, per-client rate limits. A runaway agent should not be able to DOS your server. Hard caps in the transport, not in each handler.

**Ecosystem reality check.** As of mid-2026 there are dozens of open-source MCP servers worth using off the shelf  -  Postgres, GitHub, filesystem, Slack  -  and many more that are stale or half-built. Check the last commit date and the issue tracker before you depend on one. We maintain a curated list of [the top MCP servers that matter](/blog/271-mcp-servers-top-5-that-matter) for exactly this reason.

## Production Checklist

- [ ] Resources for read-only data, tools for actions, no overlap
- [ ] All tool inputs validated with Zod or equivalent at the handler boundary
- [ ] Long-running tools return job IDs, status exposed as a resource
- [ ] Stderr logging with structured fields on every request
- [ ] MCP Inspector smoke test in CI
- [ ] Versioned server name, additive schema changes only
- [ ] Auth (OAuth 2.1 or signed tokens) for any HTTP-transport server
- [ ] Per-tool rate limits and timeouts at the transport
- [ ] Replay capture for debugging
- [ ] Documented client config snippet in your README

MCP is the right tool when your integration is *something a system owns* and *should be reusable across agents*. It is the wrong tool when you have three handlers tightly coupled to one prompt. Get the boundary right, and the rest of the spec is straightforward engineering.

For more on the broader Claude developer stack, see our guides on [tool use patterns](/blog/tool-use-claude-api-production-patterns) and [prompt caching](/blog/prompt-caching-claude-api-production-guide).



NVIDIA Nemotron 3 Super: A Developer's Guide to the 120B Hybrid MoE
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## What Nemotron 3 Super Actually Is

NVIDIA shipped Nemotron 3 Super on March 11. The headline number is 120 billion total parameters with 12 billion active per token, but the parameter count is the least interesting thing about this release. What matters for anyone building on top of it is the architecture, the reasoning controls, and the fact that NVIDIA published the full training pipeline alongside the weights.

The model is a Latent Mixture of Experts Hybrid Mamba Transformer. Four words doing a lot of work. Each one corresponds to a real architectural decision that affects how you serve the model, how much it [costs](/blog/ai-coding-tools-pricing-comparison) to run, and which workloads it handles well. This post walks through the pieces, then shows the code you need to actually use it.

For the visual breakdown of the announcement and a live demo, watch the [companion video on the channel](https://www.youtube.com/watch?v=JNAvKGU2mOo). Everything below is the practitioner's version.

## The Architecture, Decoded

Standard mixture of experts routes raw token embeddings to a small subset of expert feedforward networks. You save compute because only a fraction of the experts fire per token. The cost is memory bandwidth: every active expert still needs its weights resident on the device.

Latent MoE compresses tokens into a lower dimensional latent representation before routing. Experts then operate on the compressed view. The compression frees enough budget that NVIDIA can fit roughly 4x more experts at the same compute cost. More experts means more specialization, which translates to better performance on niche tasks (code in unusual languages, math at the edges of training data, multi-step planning) without the inference bill that a dense 120B model would carry.

The hybrid part is Mamba. Transformer attention layers handle reasoning steps that benefit from arbitrary token-to-token routing. Mamba state space layers handle the long stretches of sequence where attention's quadratic cost would dominate. The result is a model that uses the full 1 million token context window without falling over. NVIDIA reports 4x higher KV cache plus SSM cache utilization compared to a pure transformer at the same sequence length.

Multi-token prediction is the third lever. The model predicts multiple future tokens per forward pass instead of one. In practice this gives roughly 3x tokens per step at inference time when the speculative predictions hit. Combined with NVFP4 pretraining (4 bit floating point during training, which roughly doubles training throughput vs FP8), you get a model that is both cheaper to train and cheaper to serve than its parameter count would suggest.

## Hardware Requirements

The model is sized to fit comfortably on a single H100 node or a workstation with two or three high memory consumer cards once quantized. Concrete starting points:

- **Full precision serving**: 8x H100 80GB. Recommended for production multi-tenant inference where throughput matters and you want headroom for the 1M context.
- **Single node serving**: 4x H100 80GB or 2x H200 141GB. Works for most teams. KV cache plus SSM cache fits with margin.
- **Workstation, FP4 quantized**: A pair of RTX 6000 Ada cards (48GB each), or a DGX Spark. This is the dev box configuration. Speeds are lower but the model loads end to end with reasoning enabled.
- **Single GPU, heavy quantization**: Possible on an 80GB H100 with INT4 plus expert offloading, but expect significant throughput penalties. Prototype only.

If you are evaluating before committing to infrastructure, NVIDIA NIM exposes the model via an [OpenAI](/blog/openai-vs-anthropic-2026) compatible API at no charge for moderate volumes. Use that for the first round of validation.

## Calling the Model: NIM via OpenAI SDK

The simplest path is the hosted endpoint. Nemotron 3 Super on NVIDIA NIM speaks the OpenAI chat completions protocol, so any existing client works.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://integrate.api.nvidia.com/v1",
    api_key="nvapi-your-key-here",
)

response = client.chat.completions.create(
    model="nvidia/nemotron-3-super-120b-a12b",
    messages=[
        {"role": "system", "content": "You are a careful code reviewer."},
        {"role": "user", "content": "Refactor this Python function for clarity: ..."},
    ],
    temperature=1.0,
    top_p=0.95,
    max_tokens=2048,
    extra_body={
        "enable_thinking": True,
    },
)

print(response.choices[0].message.content)
```

The recommended sampling settings (temperature 1.0, top_p 0.95) come straight from the model card. Both reasoning on and reasoning off use the same sampler. The `extra_body` dict carries Nemotron specific flags through the OpenAI client.

## Reasoning Modes

Nemotron 3 Super exposes three reasoning controls. Pick the one that matches the workload:

| Flag | Behavior | When to use |
|---|---|---|
| `enable_thinking: True` | Full chain of thought before answering | Multi step reasoning, agentic tool use, hard math, tricky code refactors |
| `enable_thinking: False` | Direct answer, no visible thinking trace | Chat, summarization, classification, anything latency sensitive |
| `low_effort: True` | Reduced reasoning tokens, faster | Light reasoning where you still want some deliberation |
| `reasoning_budget: ` | Hard cap on reasoning tokens | Cost control in production, prevent runaway thinking |

The reasoning budget is the most useful flag once you ship to production. Without it, a hard prompt can spend 8000+ tokens deliberating before producing the answer. With `reasoning_budget: 1024` you cap the thinking phase and force the model to commit. Tune the cap per workload.

## Self Hosting with Transformers

For teams that want the weights local, Hugging Face hosts the model under `nvidia/nemotron-3-super-120b-a12b`. The custom Mamba and latent MoE layers ship in the model repo, so you need `trust_remote_code=True` on load.

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "nvidia/nemotron-3-super-120b-a12b"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
    trust_remote_code=True,
)

messages = [
    {"role": "system", "content": "You are a precise SQL assistant."},
    {"role": "user", "content": "Write a query that returns daily active users for the last 30 days from a table called events(user_id, ts)."},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    return_tensors="pt",
    enable_thinking=True,
).to(model.device)

with torch.inference_mode():
    output = model.generate(
        inputs,
        max_new_tokens=1024,
        temperature=1.0,
        top_p=0.95,
        do_sample=True,
    )

print(tokenizer.decode(output[0][inputs.shape[-1]:], skip_special_tokens=True))
```

`apply_chat_template` is the right entry point. It wires the reasoning flag into the prompt template so the model sees the correct control tokens. Skipping the template and concatenating strings by hand is a common source of degraded outputs.

## Production Serving with Triton and TensorRT LLM

For real deployments, the Hugging Face path is a starting point, not a destination. NVIDIA's serving stack for Nemotron 3 Super is Triton Inference Server with the TensorRT LLM backend. The conversion path looks like this:

```bash
# 1. Pull weights
huggingface-cli download nvidia/nemotron-3-super-120b-a12b \
    --local-dir ./nemotron-3-super

# 2. Build a TensorRT LLM engine
python -m tensorrt_llm.commands.build \
    --checkpoint_dir ./nemotron-3-super \
    --output_dir ./engines/nemotron-3-super-bf16 \
    --gemm_plugin bfloat16 \
    --max_input_len 131072 \
    --max_seq_len 1048576 \
    --max_batch_size 8 \
    --tp_size 8

# 3. Stage in the Triton model repository
mkdir -p model_repo/nemotron-3-super/1
cp -r engines/nemotron-3-super-bf16/* model_repo/nemotron-3-super/1/

# 4. Launch Triton
tritonserver --model-repository=model_repo \
    --http-port=8000 \
    --grpc-port=8001 \
    --metrics-port=8002
```

Two flags matter most. `--max_seq_len 1048576` tells the engine to allocate KV plus SSM cache for the full 1M context. If you only ever need 128k, drop this and you reclaim significant memory. `--tp_size 8` matches an 8 GPU H100 node. For 4x H200 use `--tp_size 4` with FP8 quantization to fit.

Once Triton is up, the Python client looks like any other Triton call:

```python
import tritonclient.http as httpclient
import numpy as np

client = httpclient.InferenceServerClient(url="localhost:8000")

prompt = "Explain the difference between Mamba and standard attention in three sentences."
inputs = [
    httpclient.InferInput("text_input", [1, 1], "BYTES"),
    httpclient.InferInput("max_tokens", [1, 1], "INT32"),
    httpclient.InferInput("temperature", [1, 1], "FP32"),
]
inputs[0].set_data_from_numpy(np.array([[prompt]], dtype=object))
inputs[1].set_data_from_numpy(np.array([[512]], dtype=np.int32))
inputs[2].set_data_from_numpy(np.array([[1.0]], dtype=np.float32))

result = client.infer(model_name="nemotron-3-super", inputs=inputs)
print(result.as_numpy("text_output")[0][0].decode("utf-8"))
```

For continuous batching, dynamic reasoning budgets, and streaming, use the TensorRT LLM in flight batching backend rather than the simple ensemble shown above. The model card includes a reference Triton config that handles all of this.

## Benchmarks Worth Quoting

NVIDIA published numbers across the standard reasoning and coding suites. The ones that matter for evaluation:

- **MMLU Pro**: Competitive with the leading sub 250B open weight models, with a meaningful jump in reasoning on mode.
- **LiveCodeBench**: Strong on the coding subset, helped by the 10 billion token reasoning and coding pre-training corpus.
- **SWE Bench Verified**: This is where the NeMo RL Gym training shows up. NVIDIA reports roughly 2x intelligence index over the previous Nemotron generation on agent style tasks.
- **Long context retrieval**: Maintains accuracy across the full 1M window, which is the entire point of the hybrid Mamba design.

Benchmarks are vibes. Run your own evals on your own workload before committing.

## When to Pick This Over the Alternatives

Nemotron 3 Super is the right call when:

- You are already on NVIDIA hardware and want a model that is tuned for that stack end to end (NVFP4, TensorRT LLM, NIM).
- You need a long context window that actually works rather than one that nominally exists but degrades after 200k tokens.
- You want commercial use rights without negotiating a license.
- Your workload mixes reasoning heavy and latency sensitive requests, and you want one model that can switch modes per request.

It is the wrong call when you need a tiny model for edge inference (look at [Nemotron Nano 9B V2](/blog/nemotron-nano-9b-v2) instead), when you need vision (try [Nemotron Nano 2 VL](/blog/nemotron-nano-2-vl)), or when you are vendor agnostic and your stack lives on AMD or Apple Silicon.

## Where the Family Goes Next

Nemotron 3 ships in three sizes. Nano (30B with 3B active) is shipping. Super (120B with 12B active) is the focus of this post. Ultra (~500B with ~50B active) lands in the first half of 2026. The architecture story is consistent across the three: same latent MoE, same hybrid Mamba, same reasoning controls, scaled across the size envelope. If Super clears the bar for your use case, plan capacity for Ultra now.

## Try It

The fastest path to a working call is NIM. Grab a key, paste the OpenAI client snippet from above, and you have a reasoning capable model behind a familiar API in five minutes. From there, the Hugging Face checkpoint and the Triton path are both well worn.

For the visual walk through, the architecture diagrams, and a side by side latency demo with reasoning on and off, watch the [Nemotron 3 Super video](https://www.youtube.com/watch?v=JNAvKGU2mOo). For more on the family, see the [Nemotron Nano 9B V2 deep dive](/blog/nemotron-nano-9b-v2) and the [Nano 2 VL post](/blog/nemotron-nano-2-vl).



OpenAI AgentKit in Production: An Honest Builder's Review
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## What AgentKit Actually Bundles

OpenAI's AgentKit launch was three products dressed up as one announcement. If you treat it as a single thing, you will be confused. If you split it apart, each piece has a clear job:

For the design side of the same problem, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) with [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

- **Agent Builder**  -  a visual canvas (think Figma for agents) where nodes are LLM calls, tools, branches, and human-in-the-loop checkpoints. You version flows, fork them, and run them.
- **Connector Registry**  -  a managed catalog of authenticated connectors (Gmail, Slack, GitHub, Notion, Linear, etc.) that handles OAuth, token refresh, and scope management. You stop writing OAuth code.
- **ChatKit**  -  an embeddable React widget that renders a chat UI talking to your agent flow. Think "Intercom but it is your agent." Streaming, tool-call rendering, file uploads, all included.

The shared value prop is: stop writing the boring 60% of every agent app  -  auth, UI, glue code  -  and concentrate on the actual logic. The question is whether the visual canvas is a feature or a tax.

I rebuilt my newsletter-research agent on AgentKit over a weekend. Below is what worked, what did not, and the decision tree I now use.

## Building a Real Workflow Visually

My newsletter agent does four things: pull RSS feeds, scrape new articles, cluster by topic, draft a digest. Here is the Agent Builder flow I ended up with:

```
[Trigger: Webhook] -> [Tool: RSS Fetch] -> [LLM: Filter Relevance, gpt-5.5]
   -> [Branch: relevance_score > 0.7?]
       -> yes -> [Tool: Firecrawl Scrape] -> [LLM: Summarize, gpt-5.3]
              -> [Tool: Embedding] -> [Tool: Cluster] -> [Human Approval]
              -> [LLM: Draft Newsletter] -> [Tool: Send via Resend]
       -> no -> [End]
```

Three things became immediately obvious in the visual canvas:

**Branching is dramatically clearer than code.** When I had this in TypeScript with nested `if`s, the relevance branch was buried 80 lines deep. On the canvas it is a single yellow diamond. New collaborators understand the flow in 30 seconds.

**Versioning is built-in.** Every save creates a numbered version. I can fork v12 to test a new prompt, run it side-by-side with prod v11, and promote when evals pass. Doing this in code means git branches plus a feature-flag system. Builder gives it to you free.

**Debugging is a timeline, not a log file.** When a run fails, you click the failed node and see the exact prompt, the model response, the token count, and the tool I/O. No more `console.log` archaeology.

For a side-by-side comparison of how this looks in a Claude Code-flavored designer, see [Subagent Studio](https://subagents.developersdigest.tech)  -  same visual-first thesis, different model ecosystem.

## When the Canvas Saves Time

After two weeks I have a clear pattern. The canvas wins when:

1. **The flow has more than 3 branches.** Visual branching beats nested code every time.
2. **You have non-engineering reviewers.** A PM can read the canvas. They cannot read your TypeScript.
3. **You version prompts often.** The built-in versioning is genuinely good.
4. **You need human approval steps.** AgentKit's approval node hands you a real review UI, not a Slack message hack.
5. **Your tools are in the Connector Registry.** If Gmail, Slack, GitHub, Notion are 80% of your tools, you save days of OAuth plumbing.

That last one is the sleeper feature. I was about to write Gmail OAuth for the newsletter agent. I deleted that ticket and used the Connector Registry's Gmail node. Token refresh, scope upgrade flow, error handling  -  all done.

## When I Dropped Back to Code

Three places I bailed:

**Custom embedding logic.** My clustering uses a non-OpenAI embedding model (Voyage) plus a custom HDBSCAN. AgentKit's "custom tool" node lets you call an HTTP endpoint, but the round trip added 400ms per call and cost me a node on the canvas for what was a 20-line function. I exposed a single `/cluster` endpoint on my existing API and called it as one node. Canvas stayed clean, performance stayed good.

**Tight loops.** AgentKit nodes have per-execution overhead  -  roughly 100-200ms  -  that adds up if you are looping 50 times per run. My RSS fetch processes ~80 feeds. Doing that as 80 canvas iterations was wasteful. I batched the entire fetch into one custom-tool call and let my own code handle the loop.

**Streaming token-level logic.** If you need to react to tokens as they stream (e.g. to cut off generation early on a stop sequence), AgentKit's node abstraction hides that. Drop to the [Responses API](/blog/openai-responses-api-migration) directly for those.

The pattern: Builder for the *workflow*, code for the *hot loops and custom math*. Same instinct as React server components  -  render the structure visually, push the heavy compute to a function.

## ChatKit: Embed in Under 30 Minutes

ChatKit is the one I expected the least and got the most from. The basic embed:

```tsx
import { ChatKit } from "@openai/chatkit-react";

export function NewsletterChat() {
  return (
     console.log("tool:", call.name)}
    />
  );
}
```

That is the full integration. You get streaming, tool-call rendering, file upload, message history, and a polished UI that matches your brand tokens. Before/after on my newsletter agent: the "before" was a 600-line custom React chat component with three streaming bugs. "After" is the snippet above plus 40 lines of theme config.

The one gotcha: ChatKit's API key is a *publishable* key scoped to a single agent. Do not paste your standard `OPENAI_API_KEY` in the browser. Generate a ChatKit-specific key in the dashboard.

## AgentKit vs. Rolling Your Own: My Decision Tree

```
Is this a one-off internal automation?
  -> Yes: AgentKit. The connector and approval nodes alone pay for themselves.
  -> No: continue.

Will non-engineers review or edit the flow?
  -> Yes: AgentKit. The canvas is the artifact they read.
  -> No: continue.

Do you need bare-metal control over streaming or model parameters?
  -> Yes: roll your own with the Responses API.
  -> No: AgentKit, drop to code only for hot paths.

Is your orchestration multi-tenant, multi-region, or > 100 RPS?
  -> Probably your own infra. AgentKit is fine for the first 90%  -  see
    [DD Orchestrator](https://orchestrator.developersdigest.tech) for when
    you need to own the runtime.
```

The honest answer for most builders shipping agent features in 2026: start in AgentKit, escape to code where it hurts. The "all visual" maximalists will hit walls; the "all code" purists are leaving days of OAuth plumbing on the table. The blended pattern wins.

For the full screen-recording walkthrough of building this newsletter agent on the canvas, the [DevDigest YouTube channel](https://www.youtube.com/@developersdigest) has the AgentKit deep-dive. The canvas is one of those things where seeing it move beats reading about it.

AgentKit will not replace your code. It will replace the *boring* 60% of your code. That is enough.



OpenAI Privacy Filter: Production PII Redaction Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

OpenAI dropped Privacy Filter as an open-weight PII redactor a few weeks back. I wired it into a real [RAG](/blog/what-is-rag) ingestion pipeline the same evening and benchmarked it against Microsoft Presidio plus a regex baseline I have been running in production for two years. The short version is that Privacy Filter caught roughly 12 percent more PII than Presidio with comparable latency once I tuned the runtime, and it caught nearly 40 percent more than the regex baseline. The longer version, including where it failed, is below.

## Why an open-weight PII model is a big deal

The privacy story for LLM pipelines has been broken for a long time. The two production options have been hosted PII APIs, which means shipping your raw documents to a third party, or rules-based tools like Presidio, which work but miss anything contextual. Both options have real downsides. The hosted APIs add egress and break the audit story. The rules-based tools miss entity types that humans easily recognize, like a street address split across three lines, or a name embedded in a meeting transcript.

For the design side of the same problem, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) with [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

An open-weight model that runs locally splits the difference. You get model-class recall without the hosted-API exposure. You can run it in the same VPC as your vector store, log every redaction decision for audit, and deterministically version the model the same way you version your other dependencies. For regulated industries that means GDPR-compliant ingestion stops being a flag-waving exercise and becomes a tractable engineering problem.

The catch is throughput. A model that runs locally only matters if it runs locally fast enough to fit in your ingestion budget. That is what I went to find out.

## Setup: weights, hardware, runtime

Privacy Filter ships on Hugging Face. The base build is small enough to run on a single consumer GPU, which is the relevant constraint for most teams. I ran it on an L40S in our staging environment for the benchmarks, then moved the production deployment to a CPU-only instance to test the worst case.

Loading the model is straightforward.

```python
from transformers import AutoTokenizer, AutoModelForTokenClassification
import torch

tokenizer = AutoTokenizer.from_pretrained("openai/privacy-filter")
model = AutoModelForTokenClassification.from_pretrained(
    "openai/privacy-filter",
    torch_dtype=torch.float16,
).to("cuda")
model.eval()
```

For production, do not call the model directly. Wrap it in a redactor class that batches inputs, applies a confidence threshold, and emits a structured redaction record for audit. Every redaction event needs to be logged with the original span, the predicted entity type, the confidence, and the replacement token. That log is the audit trail your compliance team will ask for the first time someone files a data-subject request.

```python
from dataclasses import dataclass
from typing import List

@dataclass
class RedactionEvent:
    original: str
    entity_type: str
    confidence: float
    replacement: str
    offset: int

class PrivacyFilter:
    def __init__(self, model, tokenizer, threshold: float = 0.85):
        self.model = model
        self.tokenizer = tokenizer
        self.threshold = threshold

    def redact(self, text: str) -> tuple[str, List[RedactionEvent]]:
        inputs = self.tokenizer(text, return_tensors="pt", truncation=True).to("cuda")
        with torch.no_grad():
            logits = self.model(**inputs).logits
        # decode spans, apply threshold, build events, return redacted text
        return self._apply(text, logits, inputs)
```

The full implementation is a few hundred lines once you handle batching, sliding windows for long documents, and the entity-type taxonomy. I push the redaction events into [DD Traces](https://traces.developersdigest.tech) so we can see redaction stages alongside the rest of our agent telemetry.

## Wiring it into a RAG ingestion pipeline

The pattern that makes this work in a real pipeline is pre-embed redaction. Redact before chunking, before embedding, before anything that would fan the raw text out to other systems. If a piece of PII makes it into your vector store, you will spend the next month trying to delete it cleanly. If it never makes it past ingestion, you have one place to audit and one place to fix.

Here is the ingestion shape I use.

```python
async def ingest_document(doc_id: str, raw_text: str) -> None:
    redacted, events = privacy_filter.redact(raw_text)
    await audit_log.write(doc_id=doc_id, events=events)

    chunks = chunker.split(redacted)
    embeddings = await embedder.embed_batch([c.text for c in chunks])

    await vector_store.upsert([
        {
            "id": f"{doc_id}::{i}",
            "vector": emb,
            "metadata": {"doc_id": doc_id, "redaction_count": len(events)},
            "text": chunk.text,
        }
        for i, (chunk, emb) in enumerate(zip(chunks, embeddings))
    ])
```

Two details matter here. First, the audit log writes before the embeddings, so if the embedding step fails you still have a record of what was redacted. Second, the redaction count rides on the chunk metadata, which makes downstream debugging dramatically easier. When a retrieval surfaces a chunk and a user complains it looks weird, you can tell at a glance whether the weirdness is from redaction or from something upstream.

For document storage, I keep the raw and redacted versions in [agentfs](https://agentfs.developersdigest.tech) with the audit-trailed access controls turned on. The raw version stays in a quarantine bucket that only the redactor can read. The redacted version is what flows into the rest of the pipeline. If a regulator asks what was deleted and when, the answer is in one place.

## Benchmark vs. Presidio + regex baseline

I ran all three on a 5,000-document synthetic corpus that I built from a mix of public datasets plus generated examples for the entity types I care about most. Names, addresses, phone numbers, emails, government IDs, financial accounts, and dates of birth.

Recall on names: regex 31 percent, Presidio 76 percent, Privacy Filter 88 percent. The Privacy Filter advantage concentrates on names that appear without title or honorific, which is the case where pattern-matching tools have to fall back to dictionaries. The model gets context.

Recall on addresses: regex 42 percent, Presidio 71 percent, Privacy Filter 84 percent. The biggest gap is on multi-line addresses where the line breaks confuse rules-based tools. The model handles those fine.

Recall on government IDs: regex 91 percent, Presidio 93 percent, Privacy Filter 89 percent. This is the one place the regex baseline still wins. Government IDs have well-defined formats, and pattern matching is just better at high-precision extraction of fixed formats. I now run the Privacy Filter and a regex pass in series and union the results for ID-type entities.

Latency on the L40S, batched at 32 documents: regex 8ms per doc, Presidio 22ms, Privacy Filter 41ms. On CPU only, batched at 8: regex 11ms, Presidio 38ms, Privacy Filter 280ms. CPU-only is workable for low-volume ingestion but not for anything real-time.

Precision is high across the board. False-positive redactions ran at roughly 2 percent for Privacy Filter, 4 percent for Presidio, and 0.5 percent for regex. The high false-positive rate on Presidio is mostly common nouns being flagged as proper names, which is the long-standing weakness of dictionary-driven systems.

## Failure modes

Three failure modes worth flagging.

First, context-aware misses. Privacy Filter occasionally misses PII that is technically present but heavily abbreviated or obfuscated. A name like "J. M." with no surrounding context gets through about 30 percent of the time. The fix is a cheap regex pass for initials patterns layered on top of the model output.

Second, multilingual edges. The model was trained primarily on English data and the recall drops noticeably on Spanish and Mandarin documents in my corpus. If you have multilingual content, run separate evals per language before relying on the redactor for compliance. I caught this only because we have a chunk of Spanish-language support tickets in our corpus, and an early version of the pipeline let several names through that human reviewers flagged.

Third, structured PII. The model handles natural language well and structured data badly. CSV files, JSON dumps, log lines with semi-structured fields. For those, I parse the structure first, redact each field that looks free-form, and pass the structured fields through a regex layer. Treating a CSV row as a single string and shoving it through the model gives unreliable results.

## Production checklist

Before you flip the switch, make sure you have all of these in place.

Logging. Every redaction event with original span, entity type, confidence, replacement, and document ID. This is non-negotiable for audit.

Versioning. The model checksum lives in your deploy artifact. When the model updates, the checksum changes, and your re-ingest pipeline knows to redo old documents.

Confidence threshold. Tunable per entity type, not global. Government IDs at 0.95, names at 0.80, addresses at 0.75 in my deployment. Tune against your own corpus.

Regression eval. A golden set of 200 real-or-realistic documents with hand-labeled redactions. CI runs the redactor against this set on every model bump and fails the build if recall drops more than 1 percent on any entity type.

Downstream verification. Periodically sample chunks out of the vector store and human-review them for missed PII. The model will miss things. The question is whether you find out from a human reviewer or from a regulator.

Quarantine. Raw documents go to a separate, access-restricted bucket. Only the redactor service has read access. The rest of the pipeline reads only redacted output.

I shipped the full pipeline walkthrough on the [DevDigest YouTube channel](https://www.youtube.com/@DevelopersDigest) the week after Privacy Filter dropped. The benchmark notebook is in the same repo as my eval harness. If you are running RAG against any document corpus that touches user data, this is the cheapest compliance upgrade I have shipped in the last year.



Assistants to Responses API: A Migration Field Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The Deprecation Timeline

OpenAI confirmed the Assistants API sunset in the developer changelog: new endpoints frozen now, full shutdown in 2026. Threads, runs, run-steps, and the assistant resource itself all go away. Files and vector stores survive (they moved into the Responses API surface). Function calling survives but the schema is slightly different. The Code Interpreter and File Search tools survive as built-in tools on Responses.

For the design side of the same problem, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) with [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

If you are running production code against `client.beta.threads.*` today, you have homework. I had a 14-month-old Assistants codebase running newsletter automation, customer support triage, and a chunk of internal ops. Last weekend I migrated all of it. This is the field guide  -  every cliff I hit, in order, with the code diffs that worked.

For the visual walkthrough including the eval harness I used to gate the cutover, see the [DevDigest YouTube channel](https://www.youtube.com/@developersdigest).

## Conceptual Diff: Threads vs. State

The Assistants API was *server-stateful*. You created a thread, posted messages, kicked off runs, polled for completion, and OpenAI held the conversation history. Your code did not own the state.

The Responses API is *client-stateful by default, server-stateful by opt-in*. Each call returns a `response.id`. You pass `previous_response_id` on the next call to get continuity. The server stores the chain for 30 days. After that, you reconstruct from your own DB or pass the message array explicitly.

This is the right design  -  server-only state was a footgun for compliance, debugging, and multi-region  -  but it changes how you think about every conversation:

| Assistants | Responses |
|---|---|
| `threads.create()` | nothing  -  just call `responses.create` |
| `threads.messages.create()` | include in `input` array |
| `runs.create()` + poll | `responses.create()` returns synchronously or streams |
| `run.required_action` | `response.required_action` (similar but flatter) |
| `assistants.create()` | `prompts` + system messages + tools per call |

The big mental shift: there is no `assistant` object anymore. The "assistant" is your *prompt template* + *tool list* + *model config*, which you supply per call. This is why I version mine in [Promptlock](https://github.com/developersdigest/promptlock)  -  the prompt is now a first-class artifact in your repo, not a row in OpenAI's database.

## Code-Level Migration

Here is the minimal-diff before/after for a single conversation turn. The "before" is the standard Assistants pattern most of us wrote in 2024:

```ts
// BEFORE  -  Assistants API
const thread = await client.beta.threads.create();
await client.beta.threads.messages.create(thread.id, {
  role: "user",
  content: userMessage,
});
const run = await client.beta.threads.runs.createAndPoll(thread.id, {
  assistant_id: ASSISTANT_ID,
});
const messages = await client.beta.threads.messages.list(thread.id);
const reply = messages.data[0].content[0].text.value;
```

```ts
// AFTER  -  Responses API
const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: SYSTEM_PROMPT,
  input: userMessage,
  tools: TOOLS,
  previous_response_id: priorResponseId, // null on first turn
  store: true, // 30-day server retention
});
const reply = response.output_text;
const newResponseId = response.id; // persist for next turn
```

The "after" version is shorter, synchronous on the happy path, and the conversation chain lives in two places you control: your DB row (the `response.id`) and your prompt repo (`SYSTEM_PROMPT`).

## State and History Handling

This is where I lost the most time. Three patterns I now use:

**Pattern 1: Short-lived chains (default).** Persist `previous_response_id` against your conversation row. On each turn, pass it. Trust OpenAI's 30-day retention. This is what most apps want.

```ts
await db.conversation.update({
  where: { id: convId },
  data: { lastResponseId: response.id },
});
```

**Pattern 2: Long-lived or compliance-bound chains.** Do not rely on server retention. Store every message in your DB and pass them explicitly:

```ts
const response = await client.responses.create({
  model: "gpt-5.5",
  instructions: SYSTEM_PROMPT,
  input: messages.map((m) => ({ role: m.role, content: m.content })),
  store: false, // do not retain server-side
});
```

**Pattern 3: Hybrid.** Short-lived state via `previous_response_id`, but you also write every input/output to your DB for replay and eval purposes. This is what I run in production. It is the only pattern that gives you both ergonomic continuity and full-control debugging.

The cliff I hit: I assumed `previous_response_id` would still work after 31 days. It does not  -  the server returns a 404. Wrap every call in a fallback that reconstructs from your DB if the chain is missing.

## Tool-Use Parity

Function calling works, with a flatter schema. The `tools` array is the same shape. The big differences:

- **Built-in tools.** `code_interpreter` and `file_search` are now first-class tools you enable per call. No more attaching them to an assistant.
- **Parallel tool calls.** Default-on in Responses. If your old code assumed serial tool execution, audit your handlers  -  they will now fire in parallel.
- **Streaming tool calls.** You can stream tool-call deltas, which means you can render "agent is calling tool X..." in real time. Assistants forced you to wait for `requires_action`.

Here is the parallel-tool gotcha. In Assistants, this code was safe:

```ts
// Assistants  -  implicit serial
for (const call of run.required_action.submit_tool_outputs.tool_calls) {
  const output = await runTool(call); // safe, one at a time
}
```

In Responses, the model now expects you to handle multiple tool calls concurrently. If `runTool` is not idempotent or hits a rate-limited downstream, batch your calls or `Promise.all` them with a concurrency cap:

```ts
import pLimit from "p-limit";
const limit = pLimit(3);
const outputs = await Promise.all(
  response.required_action.submit_tool_outputs.tool_calls.map((call) =>
    limit(() => runTool(call))
  )
);
```

I missed this on my first migration. The customer-support agent fired four parallel ticket-update calls to a legacy CRM and got rate-limited into oblivion within an hour.

## Eval-Driven Cutover

The migration is mechanical but the *behavior* is not always identical. Different default temperatures, different tool-call patterns, different message-formatting quirks. I would not cut over without a regression eval.

My harness: a flag-gated rollout where 10% of traffic goes to Responses, 90% to Assistants, both runs are logged with the same input, and a nightly job scores the diffs. I open-sourced the bones of this as [Agent Eval Bench](https://github.com/developersdigest/agent-eval-bench)  -  input replay, output diff, automated grading via a stronger model.

The cutover schedule that worked for me:

1. **Week 1**  -  Build the Responses path behind a feature flag. 0% traffic. Run shadow evals on logged inputs.
2. **Week 2**  -  10% live traffic. Watch error rates, latency, customer-reported issues.
3. **Week 3**  -  50% if metrics hold. Bug-fix anything weird.
4. **Week 4**  -  100%. Keep the Assistants code path in the repo with `@deprecated` comments for one more month, then delete.

Burn-down looked roughly like this in my logs:

```
Day 1: 47 endpoints calling Assistants
Day 7: 47 (built path, no traffic yet)
Day 9: 47 → 47 (10% rollout, both alive)
Day 14: 47 → 12 (cut the safe ones, kept stateful chains on assistants)
Day 21: 12 → 3 (long-lived chain edge cases)
Day 28: 0
```

The last three were the long-lived stateful chains where I needed pattern 2 above (explicit history). They took longer because I had to backfill DB writes for conversations that had been server-stateful for months.

## What I Would Do Differently

Three things in priority order:

1. **Start with eval, not code.** Get the harness running before you write a line of migration code. Without a regression signal you are migrating blind.
2. **Migrate stateless flows first.** [RAG](/blog/what-is-rag) queries, one-shot tool calls, summarization. These are mechanical search-and-replace. Build confidence before tackling stateful chains.
3. **Audit parallel tool calls explicitly.** Do not assume. Grep your `runTool` implementations for shared mutable state. The parallel-by-default behavior will find every race condition you have.

OpenAI gave us through 2026, which sounds generous until you remember every other library you depend on is also moving. Do not be the one team migrating in October.

The Responses API is the better primitive. It is simpler, more honest about state, and the streaming model finally feels native. The migration is a weekend of work for a small codebase and two weeks for a complex one. Worth it.



Prompt Caching in the Claude API: A Production Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The 90% Discount Most Teams Are Leaving On The Table

Every team I have looked at running Claude in production with a system prompt over 2k tokens is paying full freight on tokens they could be getting for a tenth of the price. Prompt caching has been generally available on the [Anthropic](/blog/anthropic-vs-openai-developer-experience) API for over a year, and it is still the single biggest cost lever most apps have not pulled. Once you set it up correctly, cached input tokens cost about 10% of normal input tokens on read, and your time-to-first-token on a long-context call drops from seconds to a few hundred milliseconds.

This guide is the version of the docs I wish I had the first time I shipped a caching layer to production. We will cover what the cache actually does, when it pays off, the SDK code you should ship, the cache-invalidation footguns, and how to monitor hit rate so you actually realize the savings instead of assuming them.

We covered the basics in our [Prompt Caching Explained](https://www.youtube.com/@developersdigest) video on YouTube. This post is the long-form, production-grade companion.

## What Prompt Caching Actually Does

Anthropic's prompt cache is a server-side, ephemeral cache keyed on the exact byte sequence of your prompt prefix. When you mark a block with `cache_control: { type: "ephemeral" }`, the API stores the model's internal state at that breakpoint. The next request that arrives within the TTL with the same prefix up to that breakpoint hits the cache.

There are two TTL options:

- **5-minute cache**  -  default, no extra cost on write, ~10% of input cost on read
- **1-hour cache**  -  [costs](/blog/ai-coding-tools-pricing-comparison) 2x normal input on write, ~10% of input on read

Cache writes are slightly more expensive than a normal call. Cache reads are dramatically cheaper. The math is simple: if you reuse the same prefix more than once or twice within the TTL window, caching wins. If you do not, it loses.

What the docs do not loudly say:

1. **The cache is a prefix cache.** It matches from the start of your messages array. Change a single token before a cache breakpoint and the entire downstream cache is invalidated.
2. **You get up to four cache breakpoints per request.** Most apps need two: one after the system prompt, one after the static document context.
3. **Cache hits are not all-or-nothing.** A request can hit the first breakpoint, miss the second, and you pay the cache-read price for the first chunk plus the cache-write price for the second.
4. **The minimum cacheable block is 1024 tokens** for Sonnet and Opus, 2048 for Haiku. Cache anything smaller and you silently pay normal price.

## When Caching Wins, And When It Is Just Overhead

The break-even is roughly: if a prefix is reused more than once or twice within five minutes, cache it. Specific scenarios where the ROI is obvious:

- **Long system prompts and skills.** Anything over 2k tokens that ships on every call.
- **[RAG](/blog/what-is-rag) with stable document context.** Retrieved chunks that are the same across a multi-turn conversation.
- **Multi-turn chat.** The conversation history grows; the early turns are stable. Cache up to the last assistant turn.
- **Batch document analysis.** Same instructions, different documents. Cache the instructions.
- **Agent loops.** Tool definitions and the system prompt are identical across iterations.

Where caching is overhead:

- **One-shot single-user queries** where the prompt will not repeat.
- **Highly dynamic prompts** where every request changes the early tokens (e.g., putting a timestamp at the top of the system prompt  -  yes, people do this).
- **Sub-1024-token prompts.** Below the floor, it is a no-op.

## The TypeScript Code You Should Actually Ship

Here is a minimal but production-shaped example using the official Anthropic SDK. It caches a long system prompt and a static knowledge-base block, leaving the user message uncached.

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const SYSTEM_PROMPT = `You are a senior support engineer for Acme Cloud.
Answer using only the provided knowledge base. Cite section IDs.
[... 3000 more tokens of policy, tone, and examples ...]`;

const KNOWLEDGE_BASE = await loadKnowledgeBase(); // ~15k tokens, stable per deploy

export async function answer(userMessage: string) {
  const response = await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    system: [
      {
        type: "text",
        text: SYSTEM_PROMPT,
        cache_control: { type: "ephemeral" },
      },
      {
        type: "text",
        text: KNOWLEDGE_BASE,
        cache_control: { type: "ephemeral" },
      },
    ],
    messages: [{ role: "user", content: userMessage }],
  });

  // Inspect cache usage on every response
  console.log({
    cache_creation: response.usage.cache_creation_input_tokens,
    cache_read: response.usage.cache_read_input_tokens,
    input: response.usage.input_tokens,
    output: response.usage.output_tokens,
  });

  return response;
}
```

Two breakpoints, two cache layers. The first request after a deploy pays the write cost on both blocks. Every subsequent request inside five minutes reads both at ~10% of input price.

For a multi-turn chat, you want a third breakpoint on the last assistant message so the growing conversation history caches as it goes:

```typescript
const messages = history.map((m, i) => {
  const isLastAssistant =
    m.role === "assistant" && i === history.length - 1;
  return {
    role: m.role,
    content: isLastAssistant
      ? [{ type: "text", text: m.content, cache_control: { type: "ephemeral" } }]
      : m.content,
  };
});
```

This is the pattern used by every production chat app shipping on Claude. It keeps the rolling conversation cached without burning a breakpoint per turn.

## Production Gotchas We Have Hit

**1. Whitespace and JSON ordering.** If your system prompt is built from a template that re-serializes a JSON object, key ordering can change between requests and silently kill the cache. Lock down your serializer or feed strings, not objects.

**2. Timestamps in system prompts.** "Today's date is 2026-04-29" at the top of the system prompt is a cache killer for every request from the next day onward. Move it into the user message or a separate uncached block at the end of the system array.

**3. Tool definitions count as part of the prefix.** If you reorder tools, you invalidate the cache. Sort tools deterministically.

**4. The 5-minute TTL is rolling.** Each cache hit refreshes the TTL. A high-traffic prompt stays warm forever. A low-traffic one dies between requests, and you pay write cost again. For prompts you call less than once every five minutes but want kept warm, use the 1-hour TTL even though the write cost is 2x  -  the math still wins above ~12 reads in an hour.

**5. Streaming responses still report cache stats.** They arrive in the final `message_delta` event. Do not assume cached calls skip usage reporting.

**6. Cache misses on "obviously identical" prompts.** Almost always one of: trailing whitespace, a Unicode normalization difference, a model version change, or a different `max_tokens`. The cache key includes more than just the text.

## Caching Inside RAG Pipelines

The mistake teams make with RAG plus caching is caching the wrong thing. The retrieved chunks are usually the most dynamic part of the prompt. The instructions and tool list are the most static. Cache those.

A clean layering for a RAG agent:

1. **Layer 1 (rarely changes):** system prompt, persona, tool definitions
2. **Layer 2 (changes per session):** user profile, account context, project metadata
3. **Layer 3 (changes per query):** retrieved chunks
4. **Layer 4 (uncached):** the user message itself

You get two breakpoints on Layer 1 and Layer 2. Layer 3 is fresh per query, no breakpoint. Layer 4 is just the user message. This pattern routinely takes a 25k-token RAG call from $0.075 input cost to about $0.012 on cache hits, with sub-second time-to-first-token.

## Monitoring Cache Hit Rate, Or You Did Not Actually Save Anything

The most common failure mode is shipping caching, declaring victory, and never noticing your hit rate is 30% because some request path is breaking the prefix. You need observability from day one. Every response includes `usage.cache_creation_input_tokens` and `usage.cache_read_input_tokens`  -  log both, then aggregate.

A useful metric is *cache hit ratio*:

```
hit_ratio = cache_read_tokens / (cache_read_tokens + cache_creation_tokens + uncached_input_tokens)
```

A healthy production prompt should sit above 0.85. Below 0.6, something is breaking the prefix and you should investigate. We built [CodeBurn](/blog/codeburn-tui-dashboard-for-claude-code-token-spend) specifically to surface this metric across runs, and the same pattern works inside any FinOps dashboard you already have. The [400-Dollar Overnight Bill](/blog/400-dollar-overnight-bill-agent-finops) post-mortem walks through what happens when you do not.

Set an alert when hit ratio drops below a threshold for any prompt template. Almost every cache regression we have shipped was caught this way: a deploy added a new dynamic field to the system prompt, and the alert fired within an hour.

## Scaling To Multi-User, Multi-Agent Systems

The cache is scoped to your API organization, not per-user. Two users hitting the same prompt prefix share the cache. This is great for shared system prompts and tool definitions. It is dangerous for anything that should be user-isolated.

Concrete patterns:

- **Shared layer first, user layer second.** Put the org-wide system prompt in the first cache block, the per-user context in the second. The first block has a much higher hit rate across all users.
- **Per-agent prompts in agent swarms.** If you run N agents with different system prompts, each one gets its own cache. Keep prompts deterministic across agent restarts.
- **Concurrent requests do not collide.** Two requests with the same prefix arriving at the same time both pay the write cost on the first call, then both read on subsequent. There is no thundering-herd protection. For very high-traffic prompts, a warm-up call on deploy is cheap insurance.

## Production Checklist Before You Ship

- [ ] System prompt over 1024 tokens, marked with `cache_control`
- [ ] Static knowledge / tool definitions in a second cache block
- [ ] No timestamps, request IDs, or non-deterministic content above any cache breakpoint
- [ ] Tool list sorted deterministically
- [ ] Cache hit ratio logged to metrics
- [ ] Alert configured for hit ratio below 0.6
- [ ] Decided 5-minute vs 1-hour TTL based on call frequency
- [ ] Tested cache stats on a smoke-test request after every deploy

Prompt caching is the closest thing to a free lunch in the Claude API. It is also the easiest optimization to ship broken and never notice. Get the breakpoints right, monitor the hit ratio, and you will pay roughly an order of magnitude less for the same workload.

For more on optimizing Claude in production, see our writeups on [tool use patterns](/blog/tool-use-claude-api-production-patterns) and [building MCP servers](/blog/model-context-protocol-mcp-server-guide).



RAG with Claude: Add Context Without Retraining
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Why RAG with Claude beats fine-tuning for almost everyone

If you have proprietary data and you want a model to answer questions about it, you have three options. Few-shot in the prompt. Retrieval-augmented generation. Fine-tuning.

For 90 percent of teams, the right answer is RAG. Few-shot dies the moment your knowledge base outgrows the context window. Fine-tuning is expensive, slow to iterate on, and changes the model's behavior in ways that are hard to predict and harder to undo. RAG keeps the base model unchanged, scales to arbitrary document counts, and lets you update the knowledge base by re-indexing instead of retraining.

The case for fine-tuning is narrower than people think. Fine-tune when you need a specific output format the base model resists, or when you have millions of high-quality examples and latency matters more than freshness. Everything else is RAG, and Claude is genuinely good at the synthesis step that turns retrieved chunks into a grounded answer.

We covered the conceptual basics in [what is RAG](/blog/what-is-rag). This post is the implementation - the parts that don't show up in the marketing diagrams.

## Chunking is the single biggest lever

Every RAG team I have worked with underestimates chunking. Then they spend three weeks tuning their retriever before realizing the problem was upstream.

The naive approach is fixed-size chunks. Split your document every 1000 tokens. This breaks the moment a sentence, a code block, or a table spans a boundary. Your retriever returns half a thought. Claude makes up the other half. You blame the embeddings.

The right approach is semantic chunking with hierarchy. Three rules.

**Respect document structure.** Markdown headings, HTML sections, code fences, table boundaries. These are pre-existing semantic units. Use them as primary chunk boundaries. Falling back to paragraph breaks before falling back to sentence breaks before falling back to fixed token windows.

**Keep parent context.** Every chunk should carry metadata about what document it came from, what section, what the surrounding heading hierarchy was. When you retrieve a chunk that says "the limit is 100 requests per minute," the retriever needs to know whether that was about the free tier or the enterprise tier. Stuff the heading path into a `context` field on each chunk.

**Overlap, but small.** A 10-15 percent token overlap between adjacent chunks helps with the case where the answer straddles a boundary. More overlap wastes embedding budget. Less overlap loses answers.

```typescript
interface Chunk {
  id: string;
  text: string;
  documentId: string;
  headingPath: string[];
  position: number;
  metadata: Record;
}

function chunkMarkdown(doc: string, docId: string): Chunk[] {
  const sections = splitByHeadings(doc);
  const chunks: Chunk[] = [];
  let position = 0;

  for (const section of sections) {
    const tokens = estimateTokens(section.body);
    if (tokens < 1200) {
      chunks.push({
        id: `${docId}:${position}`,
        text: section.body,
        documentId: docId,
        headingPath: section.headings,
        position: position++,
        metadata: { tokenCount: String(tokens) },
      });
    } else {
      const subs = splitByParagraphs(section.body, 1000, 150);
      for (const sub of subs) {
        chunks.push({
          id: `${docId}:${position}`,
          text: sub,
          documentId: docId,
          headingPath: section.headings,
          position: position++,
          metadata: { tokenCount: String(estimateTokens(sub)) },
        });
      }
    }
  }

  return chunks;
}
```

This is not glamorous code. It is the code that determines whether your RAG works.

## Retrieval: hybrid wins, almost always

Pure vector search loses to hybrid search on real workloads. The reason is that embeddings are good at semantic similarity and bad at exact-match recall. A user query for "error code E47" needs to find the chunk that contains the literal string "E47," and the embedding model sees both as roughly equivalent vectors.

Hybrid search runs both: BM25 (or a similar keyword index) and a vector search, then fuses the rankings. Reciprocal Rank Fusion is the simplest fusion algorithm and it works.

```typescript
interface ScoredChunk {
  chunk: Chunk;
  score: number;
}

function reciprocalRankFusion(
  rankings: ScoredChunk[][],
  k = 60
): ScoredChunk[] {
  const scores = new Map();
  for (const ranking of rankings) {
    ranking.forEach((item, rank) => {
      const existing = scores.get(item.chunk.id);
      const fused = 1 / (k + rank + 1);
      if (existing) existing.score += fused;
      else scores.set(item.chunk.id, { chunk: item.chunk, score: fused });
    });
  }
  return Array.from(scores.values()).sort((a, b) => b.score - a.score);
}

async function retrieve(query: string, topK = 8): Promise {
  const [vectorHits, keywordHits] = await Promise.all([
    vectorSearch(query, topK * 2),
    keywordSearch(query, topK * 2),
  ]);
  const fused = reciprocalRankFusion([vectorHits, keywordHits]);
  return fused.slice(0, topK).map((s) => s.chunk);
}
```

The next lever is reranking. Pull a top-30 from the hybrid retriever, then run a cross-encoder reranker (Cohere Rerank, BGE Reranker, or a small Claude prompt) over those 30 to pick the best 8. Reranking is expensive per query but it eliminates the long tail of retrieval misses where the right answer was at rank 12 and got dropped.

Don't skip the eval. Build a set of 50 question/answer pairs from your real data. Measure recall at 10 and answer correctness on every retrieval change. Most "improvements" don't improve anything when you measure them.

## Generation: the prompt that prevents hallucination

The retrieval is half the problem. The generation prompt is the other half.

Three things go into a RAG prompt for Claude.

A system message that tells Claude its job: answer the user's question using only the provided sources. If the sources don't contain the answer, say so explicitly. Do not use prior knowledge. Cite sources by ID.

The retrieved chunks, formatted with clear delimiters and an explicit ID per chunk so citations work.

The user's question.

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const SYSTEM_PROMPT = `You answer questions using only the provided sources.

Rules:
- Cite every claim with [source-id].
- If the sources do not contain enough information to answer, respond exactly: "The provided sources do not contain enough information to answer this question."
- Do not use general knowledge.
- Quote directly when precision matters.`;

function formatSources(chunks: Chunk[]): string {
  return chunks
    .map(
      (c) =>
        ` ")}">\n${c.text}\n`
    )
    .join("\n\n");
}

async function generate(question: string, chunks: Chunk[]) {
  return await client.messages.create({
    model: "claude-sonnet-4-5",
    max_tokens: 1024,
    system: [
      {
        type: "text",
        text: SYSTEM_PROMPT,
        cache_control: { type: "ephemeral" },
      },
    ],
    messages: [
      {
        role: "user",
        content: `Sources:\n\n${formatSources(chunks)}\n\nQuestion: ${question}`,
      },
    ],
  });
}
```

The XML-style source tags matter. Claude is trained to respect them as structural delimiters, and it cites by attribute when you ask it to. The "respond exactly" instruction is also load-bearing - without it, Claude will reach for prior knowledge when sources are thin and tell you with confidence things that aren't in your corpus.

## Citations and trust: the audit trail you actually need

Citations in the output are necessary but not sufficient. The full audit trail in production looks like this for every query:

The user question. The retrieved chunk IDs and their relevance scores. The chunks the model actually cited in its response (parsed out of the output). The final answer text.

Log all four. When a user reports a wrong answer, you can immediately see whether the failure was retrieval (right chunks not retrieved), grounding (right chunks retrieved but model ignored them), or hallucination (model cited a chunk that doesn't say what it claimed).

```typescript
function extractCitations(text: string): string[] {
  const matches = text.match(/\[([a-z0-9:.-]+)\]/g) ?? [];
  return [...new Set(matches.map((m) => m.slice(1, -1)))];
}

async function answerWithAudit(question: string) {
  const chunks = await retrieve(question);
  const response = await generate(question, chunks);
  const text = response.content
    .filter((b): b is Anthropic.TextBlock => b.type === "text")
    .map((b) => b.text)
    .join("");

  return {
    question,
    retrievedIds: chunks.map((c) => c.id),
    citedIds: extractCitations(text),
    answer: text,
    usage: response.usage,
  };
}
```

The diff between `retrievedIds` and `citedIds` is your most useful debugging signal. If the model cited zero retrieved chunks but produced an answer, that is hallucination, full stop.

## Prompt caching: the trick that makes RAG affordable

The single biggest cost optimization for production RAG is [prompt caching](/blog/prompt-caching-claude-api-production-guide) on the system prompt and any stable context (reference docs, glossaries, persona). For a chatbot that answers from a knowledge base, the system prompt and instructions don't change between queries. Cache them.

Cached reads cost 10 percent of normal input. For a 2k-token system prompt that gets called 10,000 times a day, that is the difference between a real bill and a footnote. Note that the retrieved chunks themselves don't cache well because they vary per query, but the scaffolding around them does.

The full pattern: cache system prompt as one block, put dynamic chunks in the user message, keep the structure stable so cache prefix matching works on every call. For RAG specifically the caching savings often dwarf the embedding and vector DB [costs](/blog/ai-coding-tools-pricing-comparison).

## Scaling: latency, throughput, and the parts that fail under load

End-to-end RAG latency breaks down roughly: embedding the query (50-200ms), vector search (20-100ms), keyword search (10-50ms), reranking (200-500ms), Claude generation (1-3s for short answers, 3-10s for long). The generation dominates. Optimizing anything else first is premature.

The two highest-leverage latency wins are streaming the response (start showing tokens at 800ms instead of waiting 3s for the full answer) and parallelizing retrieval calls with `Promise.all`. Both are free wins.

Throughput hits walls in two places. The vector DB starts choking past a certain QPS depending on which one you picked. And Anthropic rate limits cap your generation throughput. Both need monitoring. Both want exponential backoff with jitter on retries, which we wrote up in [Claude API reliability](/blog/claude-api-reliability-error-handling).

Cost monitoring is the part teams skip until the bill comes. Track tokens per query (input from chunks, output from generation), retrieval cost, and per-user cost. We watch this on [agent-finops](/projects) for our own RAG endpoints. The p99 cost user is usually 50x the median and is usually a bot. Catch them early.

For replay and debugging the answers that don't look right, [tracetrail](/projects) lets us step through retrieval and generation with the original chunk set so we can see whether the bug was upstream or in the prompt itself.

If you want a deeper walkthrough, the [DevDigest YouTube build of a better RAG pipeline](https://www.youtube.com/@DevelopersDigest) goes through the same architecture end to end with live debugging.

A working RAG system is mostly chunking, retrieval tuning, prompt discipline, and operational hygiene. Claude is excellent at the synthesis step. The job is to feed it the right context and verify what comes out. Get those pieces right and the rest is plumbing.



SAM 3.1: Realtime Video Segmentation in Apps
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The Latency Wall Just Fell

Every previous version of Segment Anything was a research toy in the same shape: drop in an image, get back a mask, marvel at the quality, then walk away because it could not keep up with a 30 fps camera feed. The first SAM was 600 ms per image on an A100. SAM 2 brought streaming video tracking but still cost 90+ ms per frame on consumer hardware. SAM 3.1, [announced by Meta this week](https://ai.meta.com/blog/segment-anything-model-3/), is the first version that fits inside the 33 ms budget you actually have if you want to run alongside a webcam, a Zoom feed, or a live stream.

For broader context, pair this with [Claude Computer Use: AI That Controls Your Desktop](/blog/claude-computer-use) and [GPT-5.4 for Developers: The Production Guide](/blog/gpt-5-4-developer-guide); those companion pieces show where this fits in the wider AI developer workflow.

That single change unlocks a category of products that has been blocked for two years. Realtime background replacement that does not look like 2018 Snapchat. Sports analytics that label every player and the ball without a green screen. Drone footage with persistent object IDs. Surgery assistance that tracks instruments across occlusions. The model is the same family of promptable masks, but the engineering work to integrate it is genuinely different now, and most teams will get it wrong on the first pass.

This post is the version of the docs I wish existed: what 3.1 actually changes, the minimum viable code to run it on a video stream, the gotchas that will eat your weekend, and how to stitch it into a real product instead of a demo.

## What SAM 3.1 Actually Ships

The headline number from the [Meta announcement](https://ai.meta.com/blog/segment-anything-model-3/) is a 4x speedup over SAM 2 at the same mask quality, with a smaller distilled variant (`sam3.1-tiny`) that runs at over 60 fps on a single L4. There are three concrete improvements worth pulling out of the marketing copy.

First, the memory module that tracks objects across frames is now causal and incremental. SAM 2 reprocessed a sliding window of frames every step. SAM 3.1 keeps a compressed memory bank and updates it in a single forward pass per frame. That is the change responsible for most of the speedup.

Second, the prompt encoder accepts text. You can say `segment the red car` and get a mask without clicking. Quality is below CLIP-segment style models on noisy footage but good enough for constrained product surfaces.

Third, the model exports cleanly to ONNX and CoreML out of the box. Meta is shipping the conversion scripts in the repo, which is a real shift from previous releases where the community had to figure it out.

What it does not ship: a hosted API. You run this yourself. That is fine, and arguably better, because the latency wins disappear the moment you add a network round trip.

## The Minimum Viable Pipeline

Here is what a real integration looks like. Install the SDK, load the tiny variant, and stream frames through it.

```python
import cv2
import torch
from sam3 import SAM3VideoPredictor

predictor = SAM3VideoPredictor.from_pretrained(
    "facebook/sam3.1-tiny",
    device="cuda",
    dtype=torch.float16,
)

cap = cv2.VideoCapture(0)
state = predictor.init_state()

# Prompt once on the first frame: click the object you want to track.
ret, frame = cap.read()
predictor.add_point_prompt(state, frame, point=(640, 360), label=1, obj_id=1)

while True:
    ret, frame = cap.read()
    if not ret:
        break
    masks = predictor.track(state, frame)  # dict[obj_id -> mask]
    overlay = predictor.visualize(frame, masks)
    cv2.imshow("sam3.1", overlay)
    if cv2.waitKey(1) == 27:
        break
```

That is it. Twenty lines. On an RTX 4090 this runs at roughly 90 fps. On an M3 Max via the CoreML export it runs at 35 fps, which is the threshold I care about for anything user-facing.

The `track` call is the hot path. The two failure modes you will hit are obvious in hindsight. If you push frames faster than the model can consume them you will silently drop frames in OpenCV's buffer, so always read with a queue and timestamp. If your prompt object leaves the frame and comes back the memory bank degrades, so expose a re-prompt affordance in the UI rather than assuming the model can recover forever.

## The Gotchas Nobody Mentions

The SAM 3.1 weights are 380 MB for the tiny variant and 1.4 GB for the base. Cold start on a Lambda-style serverless runtime is not viable. You want a long-running worker, ideally with a GPU pinned. If your product is bursty, a Modal or RunPod backend with autoscaling and a 60-second idle timeout is the cheapest sane option I have found.

Mixed precision is required. fp32 inference is roughly 2.4x slower with no quality benefit. Use `torch.float16` on NVIDIA, `torch.bfloat16` on Hopper, and the default fp16 in the CoreML export on Apple Silicon. The numbers in the model card are all fp16 numbers.

The text prompt path is tempting but slower than the point prompt path on the first frame because it routes through a separate text encoder. If you can capture a single click, do that instead. Reserve text prompts for batch jobs.

Audio sync is your problem. The model only handles video. If you are building a streaming product, every frame you process is a frame your audio pipeline has been waiting on. Buffer audio against frame timestamps, not wall clock, or you will ship something with 200 ms of lipsync drift.

## Where This Fits in the Agent Stack

Vision models like SAM tend to live one of two places in a product. Either as a one-shot preprocessing step that turns a video into structured data (timestamped object tracks, bounding boxes, masks) that an LLM agent then reasons about, or as an inline filter inside a realtime UI loop. SAM 3.1 is the first version where the second pattern is actually tractable.

For the preprocessing pattern, you do not need realtime. Run the base model offline, write masks and tracks to a JSON sidecar, and feed that to your downstream agent. This is the workflow we use to chop long-form video into shareable segments inside [Clips](https://clips.developersdigest.tech), our DD product for turning podcast and YouTube footage into vertical clips. The agent reads the track data, picks a focal subject, reframes the crop, and exports. SAM 3.1's speedup means the offline pass takes minutes instead of hours on a typical hour-long source.

For the realtime pattern, the question is what your agent does with the masks. The interesting answer is usually some form of selective generation: segment the speaker, regenerate only the background, composite. That is a content pipeline, and it is exactly the surface [Content](https://content.developersdigest.tech) is built around: automated B-roll generation, background swaps, and visual consistency checks across long video projects.

If you want a deeper architectural walkthrough of how these vision steps slot into a multi-agent video pipeline, I covered the full system on the [Developers Digest YouTube channel](https://youtube.com/@DevelopersDigest).

## Wiring It Into a Real Product

The non-obvious part of shipping a SAM 3.1-backed feature is not the model. It is the queue, the worker, the cache, and the failure path. Here is the shape that has worked.

A frontend pushes frames or video URLs into a job queue. A worker pool of GPU instances pulls jobs, runs SAM 3.1, and writes mask outputs to object storage as a packed video file (RLE-encoded masks, one per object, codec'd as h264 alpha) plus a manifest JSON. The frontend polls or subscribes for completion. The agent that consumes the masks reads the manifest, never the raw masks, because masks are huge and the manifest is enough for most decisions.

Cache aggressively at the input hash level. SAM is deterministic given a fixed prompt and frame, so identical inputs should never run twice. We see roughly 40% cache hits on real workloads because users re-process the same source video with different prompts, and the prompt-conditional cache key catches that.

Re-prompts are a UX problem, not a model problem. Build the affordance for users to correct a track mid-stream early. A model that is right 95% of the time still produces visibly broken output 5% of the time, and there is no amount of tuning that fixes the long tail. The right answer is letting the user click once to recover.

## What To Watch Next

Three things to keep an eye on over the next two months. First, whether the open-source community ports SAM 3.1 to WebGPU. The base model is small enough that browser inference is plausible, and that would collapse the operational story for a lot of indie products. Second, whether Meta releases a finetuning recipe for domain-specific data. The current weights are general-purpose and predictably weak on medical imagery, satellite footage, and underwater video. Third, whether the text-prompt quality improves enough to fully replace point prompts in production. That would unblock a lot of zero-touch automation.

For now, the right move is to take an existing video product, find the place where you said "we cannot do this realtime," and try it. The latency wall is gone. What you build on top of that is the interesting part.



Self-Hosting AI Agents: 5 Ways to Run Claude Code on Your Own Infra
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

The default story for [Claude Code](/tools/claude-code) is simple: install the CLI, log in with an Anthropic account, and your prompts go straight to api.anthropic.com. That works for individual developers. It does not work for regulated teams, enterprises with strict data residency rules, or anyone who wants to mix Claude with cheaper open-source models without paying retail rates on every token.

Good news: [Claude Code](/blog/what-is-claude-code-complete-guide-2026) is much more open than people realize. The CLI talks to whatever endpoint you point it at, as long as the wire protocol matches Anthropic's Messages API. That single fact unlocks a surprising amount of architectural flexibility. This post walks through five concrete patterns for self-hosting Claude Code on your own infrastructure, from a five-minute LiteLLM proxy on a laptop to a full enterprise gateway with audit logs and SSO.

If you have been running Claude Code at scale, you have probably already hit the [usage limits playbook](/blog/claude-code-usage-limits-playbook-2026) wall. These patterns are the next step.

## How Claude Code Talks to a Backend

Claude Code reads two environment variables that change the entire request path:

```bash
# Override the API endpoint
export ANTHROPIC_BASE_URL="https://your-gateway.example.com"

# Override the auth token
export ANTHROPIC_AUTH_TOKEN="your-internal-token"
```

If your gateway speaks the [Anthropic](/blog/anthropic-vs-openai-developer-experience) Messages API on the wire, Claude Code will not know the difference. This is the foundation of every pattern below.

There is also `ANTHROPIC_MODEL` for forcing a specific model name and a set of network variables (`HTTPS_PROXY`, `NODE_EXTRA_CA_CERTS`) for corporate proxies and custom certificate authorities. The Anthropic documentation calls this enterprise network configuration but it works anywhere.

## Pattern 1: LiteLLM Proxy for Local Routing

The simplest pattern. You run [LiteLLM](https://github.com/BerriAI/litellm) as a local proxy on port 4000, point Claude Code at it, and route requests to whatever provider you want behind the scenes. It takes about five minutes to set up.

```yaml
# litellm-config.yaml
model_list:
  - model_name: claude-sonnet-4-7
    litellm_params:
      model: anthropic/claude-sonnet-4-7
      api_key: os.environ/ANTHROPIC_API_KEY

  - model_name: claude-haiku-4-7
    litellm_params:
      model: bedrock/anthropic.claude-haiku-4-7
      aws_region_name: us-east-1

  - model_name: gpt-5-3
    litellm_params:
      model: openai/gpt-5.3
      api_key: os.environ/OPENAI_API_KEY

router_settings:
  routing_strategy: simple-shuffle

general_settings:
  master_key: sk-internal-team-key
```

Run it:

```bash
litellm --config litellm-config.yaml --port 4000
```

Point Claude Code at it:

```bash
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-internal-team-key"
claude
```

You now have a proxy that logs every request, enforces budget limits per virtual key, and can fall back across providers when one is rate-limited. Same Claude Code experience, full visibility into what your team is sending.

This pattern is great for individual developers and small teams. It does not give you SSO or audit logs that auditors will accept, but it solves the cost-tracking problem for under an hour of setup.

## Pattern 2: Bedrock and Vertex for Compliance

If you cannot send code to Anthropic directly because of compliance, you have two options that already speak Claude: AWS Bedrock and Google Vertex AI. Both host the same Claude models and route everything through your existing cloud account.

For Bedrock:

```bash
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
export ANTHROPIC_MODEL="us.anthropic.claude-sonnet-4-7-v1:0"
export ANTHROPIC_SMALL_FAST_MODEL="us.anthropic.claude-haiku-4-7-v1:0"
claude
```

For Vertex:

```bash
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-gcp-project"
export ANTHROPIC_MODEL="claude-sonnet-4-7@20260301"
claude
```

Claude Code knows about these flags natively. Authentication uses your existing AWS or GCP credentials, all logs flow into CloudTrail or Cloud Audit Logs, and the data never leaves your cloud account boundary. For most enterprise compliance requirements this is the cleanest answer.

The tradeoff: Bedrock and Vertex sometimes lag behind direct Anthropic on new model releases by a few weeks, and [prompt caching](/blog/prompt-caching-claude-api-production-guide) support has historically been spottier. Test before committing.

## Pattern 3: Enterprise Gateway with IAP

For organizations that need centralized identity, audit logs, and per-developer attribution, the right pattern is a self-hosted gateway behind Identity-Aware Proxy. The high-level architecture:

```
[Developer machine]
  -> Local proxy (Claude Code calls this)
  -> [Identity-Aware Proxy] (Google Workspace SSO)
  -> [FastAPI gateway on Cloud Run]
  -> Anthropic API or Bedrock
```

The local proxy is a tiny piece of software running on the developer's laptop that intercepts Claude Code's API calls, fetches a fresh OIDC token from gcloud, and forwards the request to the company gateway with `Authorization: Bearer `. IAP validates the token, confirms the user is in the right Google Workspace group, and forwards to your FastAPI service. Your service logs the request, attaches the user identity, and proxies to Anthropic.

The skeleton of the gateway service:

```python
# gateway.py
from fastapi import FastAPI, Request, HTTPException
from fastapi.responses import StreamingResponse
import httpx
import os

app = FastAPI()
ANTHROPIC_KEY = os.environ["ANTHROPIC_API_KEY"]

@app.post("/v1/messages")
async def messages(request: Request):
    user = request.headers.get("X-Goog-Authenticated-User-Email")
    if not user:
        raise HTTPException(401, "missing identity")

    body = await request.body()

    # Log who, when, what model, token estimate
    log_request(user=user, body=body)

    # Forward to Anthropic, streaming back to the client
    headers = {
        "x-api-key": ANTHROPIC_KEY,
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    }

    async def upstream():
        async with httpx.AsyncClient(timeout=None) as client:
            async with client.stream(
                "POST",
                "https://api.anthropic.com/v1/messages",
                content=body,
                headers=headers,
            ) as r:
                async for chunk in r.aiter_raw():
                    yield chunk

    return StreamingResponse(upstream(), media_type="text/event-stream")
```

Every developer sets `ANTHROPIC_BASE_URL` to the gateway and authenticates via SSO. You get a single audit log of every prompt anyone in the company sent, attributable to a specific identity. When someone leaves the company, removing them from the Workspace group revokes their access immediately. No scattered API keys to rotate.

This is the pattern that makes Claude Code viable in regulated industries. Build it once, every developer benefits.

## Pattern 4: Open-Source Models via Claude Code Router

You do not have to use Anthropic models with Claude Code. The open-source [Claude Code Router](https://github.com/musistudio/claude-code-router) project translates between Claude's wire format and any other provider, including local Ollama models, OpenRouter, Groq, DeepSeek, and Together.

Install and configure:

```bash
npm install -g @musistudio/claude-code-router

# ~/.claude-code-router/config.json
{
  "Providers": [
    {
      "name": "ollama",
      "api_base_url": "http://localhost:11434/v1/chat/completions",
      "models": ["qwen3.5-coder:35b", "deepseek-coder:33b"]
    },
    {
      "name": "openrouter",
      "api_base_url": "https://openrouter.ai/api/v1/chat/completions",
      "api_key": "$OPENROUTER_API_KEY",
      "models": ["anthropic/claude-sonnet-4-7", "google/gemini-2.5-pro"]
    }
  ],
  "Router": {
    "default": "ollama,qwen3.5-coder:35b",
    "background": "ollama,qwen3.5-coder:35b",
    "think": "openrouter,anthropic/claude-sonnet-4-7",
    "longContext": "openrouter,anthropic/claude-sonnet-4-7"
  }
}
```

Run Claude Code through the router:

```bash
ccr code
```

The router routes "thinking" tasks to Claude Sonnet on OpenRouter and routine tasks to a local Qwen model on Ollama. You pay nothing for the bulk of your tokens, get frontier-quality reasoning when you need it, and your code never leaves your laptop for the local-only routes.

This is the budget-conscious pattern. We documented the full setup in our [comparison of every AI coding tool's economics](/blog/ai-coding-tools-comparison-matrix-2026), and it pairs well with cheap GPU rentals if your laptop is not powerful enough to run a 35B model locally.

## Pattern 5: Air-Gapped on Your Own GPUs

The most extreme version. You run an open-weight coding model on your own GPUs, expose an Anthropic-compatible endpoint, and Claude Code never touches the public internet. This is what defense, healthcare, and certain financial customers require.

Stack:

- **Model:** Qwen3.5-Coder-32B or [DeepSeek](/blog/deepseek-v4-developer-guide)-Coder-33B, served via vLLM
- **Adapter:** LiteLLM in proxy mode, configured to translate Anthropic format to OpenAI format
- **Network:** All traffic stays inside the VPC, no egress rules to api.anthropic.com required

Minimal docker compose:

```yaml
services:
  vllm:
    image: vllm/vllm-openai:latest
    command:
      - --model=Qwen/Qwen3.5-Coder-32B-Instruct
      - --max-model-len=131072
      - --tensor-parallel-size=2
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 2
              capabilities: [gpu]
    ports:
      - "8000:8000"

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    environment:
      LITELLM_MASTER_KEY: sk-internal
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "4000:4000"
```

Developers connect like this:

```bash
export ANTHROPIC_BASE_URL="https://internal-claude.corp.example.com"
export ANTHROPIC_AUTH_TOKEN="$INTERNAL_TOKEN"
export ANTHROPIC_MODEL="qwen3.5-coder-32b"
claude
```

You give up some quality. Qwen3.5 and DeepSeek are excellent but not Sonnet 4.7. For most refactors, test writing, and routine feature work they are good enough. For the hard 10 percent of problems, route to the gateway pattern above when policy allows.

This pattern also pairs well with [building multi-agent workflows in Claude Code](/blog/building-multi-agent-workflows-claude-code), because cheap local inference makes fan-out architectures economical that would be cost-prohibitive against the public API.

## Watch It Built End to End

For a walkthrough of the LiteLLM and Claude Code Router patterns running side by side on a single laptop, with cost dashboards and live token streaming:



[Subscribe to Developers Digest](https://www.youtube.com/@developersdigest) for the rest of the self-hosting series.

## What to Pick

A simple decision matrix:

| Need | Pattern |
|------|---------|
| Just want cost tracking and team budgets | LiteLLM proxy (Pattern 1) |
| Compliance, no Anthropic API direct, AWS or GCP shop | Bedrock or Vertex (Pattern 2) |
| Centralized identity, audit logs, SSO for the whole org | Enterprise gateway with IAP (Pattern 3) |
| Want to slash costs by routing easy tasks to local models | Claude Code Router (Pattern 4) |
| Air-gapped, cannot send code anywhere external | Self-hosted GPUs with vLLM (Pattern 5) |

Most teams should start with Pattern 1. It is reversible, ships in an afternoon, and tells you whether your usage justifies the more invasive patterns. The teams that need Pattern 5 already know they need it; the rest are doing premature optimization.

## The Bigger Picture

The reason these patterns exist is that Anthropic made a deliberate decision to keep Claude Code's wire protocol portable. The CLI is opinionated about how it works on your machine  -  the sub-agent system, the [hooks](/blog/claude-code-hooks-explained), the worktree integration  -  but completely agnostic about which backend serves the model. That separation is rare among AI coding tools.

It also means the cost ceiling on Claude Code is a lot lower than it appears. The retail price assumes everything goes to the public API. With the patterns above, real-world team costs come down by 40 to 90 percent depending on how aggressive you are about routing, with no change to the developer experience.

If you are evaluating AI coding tools for an organization, Claude Code's self-hosting story is not a sidebar. It is one of the strongest arguments for picking it over the alternatives. Pair it with our [full 2026 comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) when you make the case to your platform team.



Shipping OpenAI Symphony in Prod: A Real-World Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Why Symphony Matters

When OpenAI open-sourced Symphony, they buried the headline number under a wall of Elixir docs: a 500% increase in PR throughput inside their own infra teams. That is not a "we shipped a chatbot" stat. That is "we replaced a junior engineering pod with a fleet of Codex agents and the kanban moves itself." The thesis Symphony forces you to internalize is *manage work, not agents*. You stop thinking about prompts and start thinking about tickets, queues, and merge gates.

For the design side of the same problem, read [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) with [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

I forked the repo on a Saturday night, pointed it at a live Linear board for one of my smaller DD products, and watched it land four PRs before I finished my coffee. This post is the unredacted ops story  -  what setup actually looks like on Apple Silicon, what the runtime feels like in production, and where it breaks.

If you want the visual demo first, the [DevDigest YouTube channel](https://www.youtube.com/@developersdigest) has the screen-recording walkthrough where Linear ticket goes in and PR comes out in under three minutes.

## Why Elixir / BEAM Was the Right Pick

Before the setup walkthrough, this matters: Symphony runs on the BEAM. That sounds like an aesthetic choice until you watch six Codex agents melt down concurrently and the supervisor tree just… restarts the failing one. No restart loop in your Node process. No half-dead Python worker holding a file lock. The actor model is what lets a single laptop juggle a real fleet without becoming a babysitting job.

If you have ever tried to orchestrate agents with a Python `asyncio` gather and a Postgres queue, you already know why this matters. Symphony's choice to put each agent run in its own supervised process means a runaway Codex session crashes itself, not the orchestrator.

## Setup: From `git clone` to First Run

The README is honest about engineering preview status, but it underplays how rough Erlang/OTP install is on Apple Silicon. Here is the actual sequence that worked on M3 Max, macOS 15:

```bash
# 1. Erlang via asdf (brew install erlang takes ~30min and frequently fails)
brew install asdf
asdf plugin add erlang
KERL_CONFIGURE_OPTIONS="--without-javac --with-ssl=$(brew --prefix openssl@3)" \
  asdf install erlang 27.1.2
asdf install elixir 1.17.3-otp-27

# 2. Clone and bootstrap
git clone https://github.com/openai/symphony.git
cd symphony
mix deps.get
mix ecto.setup
```

Three env vars do real work:

```bash
export OPENAI_API_KEY=sk-...
export LINEAR_API_KEY=lin_api_...
export SYMPHONY_WORKSPACE_ROOT=$HOME/symphony-runs
```

`SYMPHONY_WORKSPACE_ROOT` is the one most people miss. Symphony clones target repos into ephemeral subdirectories under that root. If you do not set it, it picks `/tmp` and macOS nukes it on reboot mid-run. Ask me how I know.

For Codex auth, Symphony uses your existing `codex` CLI session, so `codex login` once on the host and Symphony inherits it. The Linear API key needs `read` and `write` on issues  -  `read` only is not enough because Symphony writes status comments back to the ticket.

## Anatomy of a Run

Once you boot Symphony with `mix phx.server` and open the dashboard at `localhost:4000`, you connect a Linear team. Symphony pulls open issues with the label `agent` (configurable) and queues them. Each run looks like this:

1. **Plan phase**  -  Codex reads the ticket, the linked repo, and produces a plan in a sandboxed worktree.
2. **Implement phase**  -  Codex edits files, runs tests, iterates. The whole thing happens inside a per-run git worktree under `SYMPHONY_WORKSPACE_ROOT`.
3. **Review phase**  -  Symphony pushes a branch and opens a PR with the ticket linked.
4. **Status phase**  -  Symphony comments back on the Linear ticket with the PR URL and moves it to `In Review`.

The isolation boundary is a git worktree plus a process-level chroot of sorts. The agent sees the repo, your shell, your test runner. It does not see your other repos, your home dir, your secrets file. That is the whole point. If you want true container-level isolation, you can wire `SYMPHONY_RUN_COMMAND` to wrap each run in a Docker invocation  -  there is a stub for this in `lib/symphony/runner.ex` but it is not wired up by default.

## Production Hardening

Out of the box Symphony will happily spawn 20 concurrent Codex runs and burn $40 in 15 minutes. Three knobs matter:

```elixir
# config/runtime.exs
config :symphony, Symphony.Orchestrator,
  max_concurrent_runs: 3,
  max_run_duration_ms: 20 * 60 * 1000,
  max_cost_per_run_usd: 2.50
```

`max_cost_per_run_usd` is the one I would not ship without. Symphony tracks token spend per run via the [OpenAI API](/blog/openai-responses-api-migration) response headers and will kill the run if it exceeds the cap. I had a single ticket on a gnarly refactor consume $11 in tokens before I added this. Now nothing crosses $2.50 without my review.

For observability, Symphony emits OTel spans for every phase. I pipe them into [DD Traces](https://traces.developersdigest.tech) so I can see exactly where each run spent its tokens  -  turns out 60% of cost on most tickets is the plan phase re-reading the same files. Caching prompts for the implement phase cut my bill in half.

The other thing nobody documents: Symphony's `kill_run/1` is a soft kill. It signals the agent process. If Codex is mid-API-call, the call completes and bills you. If you actually want hard-kill semantics, patch `lib/symphony/runner.ex` to `Process.exit(pid, :kill)` instead of the graceful path.

## Where Symphony Breaks Down

This is engineering preview, not GA, and it shows in three places:

**No auth roles.** Anyone with the dashboard URL can trigger runs and spend your tokens. Put it behind a VPN or Cloudflare Access. There is no built-in user model.

**No native multi-repo.** Each Linear team maps to one repo. If your ticket touches two repos, Symphony picks the first and the agent fakes the rest. I hit this on a frontend/backend coordinated change and had to manually split the ticket.

**No retry queue.** When a run fails (rate limit, transient git error, flaky test), Symphony marks the ticket failed and stops. There is no exponential-backoff retry. I built a 30-line GenServer wrapper that catches `:run_failed` events and reschedules with a backoff. OpenAI will probably ship this soon but until then, expect to write it.

OpenAI's own README says "do not run this in production yet." Take them seriously. This is a *fork-and-run-on-your-laptop* tool today, not a multi-tenant SaaS.

## My Ship-It Verdict

For a solo dev or a small team where one person is the platform owner, Symphony is the most leveraged thing I have run this year. Six Codex agents working a backlog feels like running a junior team without standups. But it is *your* responsibility to keep the wheels on  -  cost caps, observability, kill switches.

If you are at a 50-person eng org, wait for the productized version. The auth and multi-repo gaps are real.

If you want a lighter-weight orchestration pattern that does not require Erlang, check out [DD Orchestrator](https://orchestrator.developersdigest.tech)  -  same management-not-agents thesis, simpler runtime, less throughput. The right pick depends on how much volume you are actually pushing through.

What I would steal for any agent stack regardless of which orchestrator you pick: per-run cost caps, OTel-everywhere, sandboxed git worktrees, and the discipline to label tickets agents are allowed to touch. Those four habits alone are worth the whole exercise.

The 500% PR uplift number is real, but only if you do the ops work. Symphony hands you the chassis. You still have to drive.



Tool Use in the Claude API: Production Patterns for Reliable Agents
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Tool Use Is Powerful And Fragile

Tool use is the feature that turns Claude from a chatbot into an agent. It is also the feature that, deployed casually, fails silently in ways that are hard to root-cause. We have run Claude tool use through production paths handling tens of thousands of daily calls across [DD products](/blog/devdigest-apps-ecosystem), and almost every outage has been traced to one of a small number of patterns: ambiguous schemas, missing error handling on the executor side, runaway loops, or tools the model thought existed.

This is the production playbook. Schema design, the execution layer, multi-step loops, security, and what to monitor. Code samples are TypeScript with the official [Anthropic](/blog/anthropic-vs-openai-developer-experience) SDK because that is what most of our deployed agents run on.

We walked through a live build of one of these in our [Building Reliable Claude Agents](https://www.youtube.com/@developersdigest) video. This is the deeper writeup.

## How The Tool Use Loop Actually Works

You pass `tools` to `messages.create`. Claude either responds with text, or with one or more `tool_use` blocks. You execute the tool, send back a `tool_result` block in the next user message, and the loop continues until Claude stops requesting tools.

The thing nobody tells you up front: **Claude can hallucinate a tool call**. It is rare on Sonnet 4.5 and above, but it happens, especially when your tool schemas overlap or when the user request is ambiguous. Your executor has to handle "tool name not found" as a normal case, not a crash. We will get to that.

A minimal correct loop looks like this:

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const tools: Anthropic.Tool[] = [
  {
    name: "get_weather",
    description:
      "Get the current weather for a specific city. Returns temperature in Celsius and a short conditions string.",
    input_schema: {
      type: "object",
      properties: {
        city: {
          type: "string",
          description: "City name, e.g. 'San Francisco' or 'Tokyo'",
        },
      },
      required: ["city"],
    },
  },
];

async function runAgent(userMessage: string) {
  const messages: Anthropic.MessageParam[] = [
    { role: "user", content: userMessage },
  ];

  for (let iter = 0; iter < 10; iter++) {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 1024,
      tools,
      messages,
    });

    messages.push({ role: "assistant", content: response.content });

    if (response.stop_reason !== "tool_use") {
      return response;
    }

    const toolResults: Anthropic.ToolResultBlockParam[] = [];
    for (const block of response.content) {
      if (block.type !== "tool_use") continue;
      const result = await executeTool(block.name, block.input);
      toolResults.push({
        type: "tool_result",
        tool_use_id: block.id,
        content: JSON.stringify(result),
        is_error: result.error !== undefined,
      });
    }

    messages.push({ role: "user", content: toolResults });
  }

  throw new Error("Max iterations exceeded");
}
```

Note three deliberate choices: a hard iteration cap, `is_error` set on the result when the tool fails, and `tool_use_id` matched correctly per call. Skip any of these and you are one bad day from an outage.

## Designing Schemas That Do Not Get Misused

Schema quality is the single biggest predictor of tool-use reliability. The model picks tools based on names, descriptions, and parameter docs. If two tools sound similar, it will pick wrong, and the failure is invisible until a user complains.

Bad:

```typescript
{ name: "search", description: "Search for information." }
{ name: "lookup", description: "Look up information." }
```

Good:

```typescript
{
  name: "search_internal_kb",
  description:
    "Search Acme's internal knowledge base of product docs and runbooks. Use for questions about Acme features, APIs, or internal processes. Do not use for general web search.",
}
{
  name: "search_web",
  description:
    "Search the public web via Google. Use for current events, third-party software, or anything not covered by the internal KB.",
}
```

Rules of thumb we have converged on:

1. **Names should be verb-noun and disambiguated by domain.** `get_user`, `get_user_by_email`, `list_users_in_org`  -  not `get`, `find`, `lookup`.
2. **Descriptions should say when not to use the tool.** This is the highest-leverage line in any tool description.
3. **Parameter descriptions should include format examples.** Especially for dates, IDs, and enums.
4. **Use `enum` aggressively** on string parameters with a fixed set of valid values. The model respects enums far more reliably than prose constraints.
5. **Mark required fields explicitly.** Optional fields invite hallucinated defaults.

A diagnostic worth running: take your tool list, paste it into Claude with the user message "which tool would you call for X?" for ten realistic prompts. If it picks wrong on any, the schemas are ambiguous.

## A Production-Grade Execution Layer

The naive executor is `tools[name](input)`. The production executor handles: unknown tool names, schema validation, timeouts, retries, structured error responses, and logging. Here is the shape we run.

```typescript
import { z, ZodSchema } from "zod";

interface ToolDef {
  name: string;
  schema: ZodSchema;
  handler: (input: I) => Promise;
  timeoutMs: number;
}

const registry = new Map>();

function register(def: ToolDef) {
  registry.set(def.name, def);
}

async function executeTool(name: string, rawInput: unknown) {
  const def = registry.get(name);
  if (!def) {
    return { error: `Unknown tool: ${name}. Available: ${[...registry.keys()].join(", ")}` };
  }

  const parsed = def.schema.safeParse(rawInput);
  if (!parsed.success) {
    return { error: `Invalid input: ${parsed.error.message}` };
  }

  const start = Date.now();
  try {
    const result = await Promise.race([
      def.handler(parsed.data),
      new Promise((_, rej) =>
        setTimeout(() => rej(new Error("timeout")), def.timeoutMs)
      ),
    ]);
    log("tool_call", { name, durationMs: Date.now() - start, ok: true });
    return { data: result };
  } catch (err) {
    log("tool_call", { name, durationMs: Date.now() - start, ok: false, err: String(err) });
    return { error: `Tool failed: ${err instanceof Error ? err.message : String(err)}` };
  }
}
```

The critical detail: **errors come back as data, not exceptions**. When you send `is_error: true` in the `tool_result`, Claude reads the error message and usually does the sensible thing  -  retries with corrected input, picks a different tool, or tells the user. Throwing an exception kills the loop.

This is also where you do retries. Transient network errors on a downstream API should retry inside the handler with exponential backoff. Permanent errors (4xx, validation) should return the error to Claude and let the model decide. The mental model: the handler is responsible for transient retries, Claude is responsible for semantic recovery.

## Multi-Step Workflows And Loop Control

Real agents chain calls. The user asks "summarize last week's support tickets and email me the top three categories." That is `list_tickets` → `categorize` → `send_email`. Three sequential tool calls with state flowing between them.

Two failure modes show up here:

1. **Infinite loops.** The model gets stuck calling the same tool with slightly different inputs. Always cap iterations. We use 10 for user-facing flows, 25 for batch jobs.
2. **State drift.** The model loses track of intermediate results in long chains. The fix is to summarize state explicitly: have the agent emit a `current_state` text block between tool calls, or have the orchestrator append a synthetic "so far you have learned: ..." message every N iterations.

For workflows above ~5 steps, consider not solving the orchestration with a single agent loop. Decompose into a planner that emits a DAG and an executor that runs nodes. We covered this pattern in [Seven AI Agent Orchestration Patterns](/blog/seven-ai-agent-orchestration-patterns).

## Security: Tools Are An Attack Surface

A tool is anything Claude can invoke. The user can influence what Claude invokes. So a user can, transitively, influence your tools. This is prompt injection 101 and it bites every team that ships tool use without thinking about it.

Hardening checklist we apply to every tool:

- **Allowlist what each tool can touch.** A `read_file` tool should be scoped to a sandbox directory. A `query_db` tool should only see specific tables. Never trust the LLM to constrain itself.
- **Validate inputs at the boundary.** Zod or equivalent. Reject anything outside the schema before the handler runs.
- **No string-concatenated SQL or shell commands.** Parameterize. If a tool builds a shell command, Claude can be coerced into building a malicious one.
- **Rate-limit per session.** A runaway agent loop should not be able to hammer your downstream APIs. Per-tool, per-session limits with hard fails.
- **Log everything.** Every tool call, every input, every result. You will need this for incident response, not for debugging.
- **Treat tool descriptions as untrusted documentation.** If a downstream [MCP server](/blog/complete-guide-mcp-servers) sends you a tool with a hostile description, you will execute it. Audit imported tool definitions.

The red-team test: assume the user message is hostile. Can they extract data they should not see, or trigger an action they should not be able to trigger? If yes, scope the tool tighter.

## Scaling Tool Definitions

Performance and reasoning quality degrade with more tools. The breakpoints we have observed:

- **Up to ~20 tools:** no measurable degradation
- **20-50 tools:** occasional wrong-tool selection on ambiguous queries
- **50-100 tools:** noticeable slowdown in selection, more hallucinated calls
- **100+ tools:** you need a router

For agents with large tool surfaces (e.g., MCP servers exposing 50+ resources each), use a two-stage pattern: first call selects a *tool category* with a small fixed tool list, second call exposes only the tools in that category. This is roughly how [Claude Code](/blog/what-is-claude-code-complete-guide-2026) handles its bundled toolset internally.

Cost-wise, every tool definition lives in the system prompt and ships on every request. Cache them. The [prompt caching guide](/blog/prompt-caching-claude-api-production-guide) covers exactly how to put tool definitions inside a cache block so a 50-tool agent does not bleed money on input tokens.

## What To Monitor

Four metrics that catch almost every tool-use regression in production:

1. **Tool call success rate** per tool. A drop on one tool usually means a downstream API change.
2. **Average iterations per session.** A creep upward means the model is working harder for the same outcomes  -  usually a schema regression.
3. **Hallucinated tool name rate.** Every time `executeTool` returns "Unknown tool". Should be near zero. Spikes mean someone deployed a tool list change that broke a code path.
4. **Tool latency P95.** Slow tools cascade through the loop. Cap with timeouts and watch the P95 per tool.

The easy mistake is monitoring only the agent's overall success rate. By the time that drops, you have hours of broken sessions. Tool-level metrics catch problems within minutes.

## Closing Checklist

- [ ] All tool names verb-noun and unambiguous
- [ ] Descriptions include "do not use for X"
- [ ] Schemas use enums and required fields aggressively
- [ ] Executor returns errors as data, not exceptions
- [ ] Hard iteration cap on every loop
- [ ] Inputs validated at the handler boundary
- [ ] Per-tool rate limits and timeouts
- [ ] Tool definitions cached via prompt caching
- [ ] Per-tool success/latency metrics in your dashboard
- [ ] Red-team review of every tool with side effects

Tool use is a sharp edge. Treat it like one and it scales cleanly. For the next layer up  -  long-running, stateful integrations  -  see our guide to [building MCP servers](/blog/model-context-protocol-mcp-server-guide).



Vercel's Agentic Infrastructure Stack Explained
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## Vercel Picked a Side

For two years the conversation about what an "agent stack" actually means has been a list of vendors and a vague hand-wave. LangChain for orchestration, [OpenAI](/blog/openai-vs-anthropic-2026) for inference, some vector DB, some queue, some place to run untrusted code, some flagging system bolted on after the first incident. Every team rebuilt the same plumbing.

For the larger agent workflow map, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they give the architecture and implementation context this piece assumes.

Vercel's [agentic infrastructure announcement](https://vercel.com/blog/agentic-infrastructure) is the first time a major platform has named the primitives explicitly and shipped them as a coherent stack. Four pieces: **AI Gateway** for model routing, **Sandbox** for code execution, **Flags** for runtime control, and **Microfrontends** for composing UIs that agents render into. None of these are individually novel. The bet is that you want them as one platform with one auth model, one observability surface, and one billing line.

This post is a working developer's read of what was announced, what it looks like in code, and where the seams are. I am skeptical of platform consolidation as a default but I think Vercel got the abstractions mostly right, and the parts they got wrong are the parts you can route around.

## The Four Primitives

**AI Gateway** is a model-router with a single OpenAI-compatible endpoint. Point your SDK at `https://gateway.ai.vercel.com/v1`, pass a model identifier like `anthropic/claude-opus-4.7` or `openai/gpt-5.3`, and get back a response. The gateway handles failover, caching, rate limit smoothing across keys, and per-request cost tracking. You can also define routing policies - for example, "route reasoning-heavy prompts to opus, route summarization to haiku" - without rewriting your application code.

**Sandbox** is a microVM-backed code execution environment with a Node-like API. You hand it a snippet of Python, JavaScript, or shell, and it runs in an isolated VM with file system, network egress controls, and a 60-second to 30-minute lifetime depending on plan. This is the primitive every [coding agent](/blog/what-is-an-ai-coding-agent-2026) has been hand-rolling on top of Firecracker, E2B, or Modal. Vercel collapsed it.

**Flags** is the lightweight feature flag service Vercel has been quietly building for two years, now positioned as the runtime control plane for agents. Toggle which model an agent uses, which tools it can call, which prompt template applies to which user, all from a dashboard, all evaluated at the edge. There is no SDK weight beyond a tree-shakeable function call.

**Microfrontends** lets you compose UI from independently deployed apps. The agent angle is that an agent can render a generated UI fragment from a separate deployment without taking over the whole page. Think generative UI scoped to a region of your existing product.

## What It Looks Like in Code

The minimal agent that uses three of the four primitives. AI Gateway for the model call, Sandbox for tool execution, Flags for the kill switch.

```ts
import { generateText } from "ai";
import { gateway } from "@vercel/ai-gateway";
import { Sandbox } from "@vercel/sandbox";
import { flag } from "@vercel/flags";

const codeExecEnabled = flag({
  key: "agent_code_exec",
  defaultValue: false,
});

export async function runAgent(userPrompt: string, userId: string) {
  const model = await flag({
    key: "agent_model",
    defaultValue: "anthropic/claude-sonnet-4.7",
  })();

  const result = await generateText({
    model: gateway(model),
    system: "You are a code agent. Use the run_code tool when needed.",
    prompt: userPrompt,
    tools: {
      run_code: {
        description: "Execute Python in a sandbox",
        parameters: { code: "string" },
        execute: async ({ code }) => {
          if (!(await codeExecEnabled({ user: userId }))) {
            return { error: "Code execution disabled for this user" };
          }
          const sandbox = await Sandbox.create({ runtime: "python3.12" });
          const out = await sandbox.exec(code, { timeout: 30_000 });
          await sandbox.destroy();
          return out;
        },
      },
    },
  });

  return result.text;
}
```

A few things worth pointing out.

The `gateway(model)` call returns a model object that the Vercel AI SDK already understands. There is no separate fetch client to manage. If the upstream provider 503s, the gateway transparently fails over to your configured fallback, which is set in the dashboard rather than in code. That is the right place for it because failover policy is an ops concern, not a code concern.

The `flag` evaluation happens at the edge with a typical latency of single-digit milliseconds. You can target by user ID, geography, cohort, or anything in the request. The `agent_model` flag in the example lets you do canary rollouts of new model versions to 5% of users without a deploy.

The Sandbox lifecycle is explicit. You create, you exec, you destroy. There is no ambient pool, which is good for predictability and bad if you are running thousands of short executions per second. For high-volume cases there is a `Sandbox.persistent` API that keeps a warm pool, but you pay for it.

## The Gotchas

**Pricing is not free of routing logic.** AI Gateway adds a small markup on token [costs](/blog/ai-coding-tools-pricing-comparison) and a per-request fee on top. For a high-volume product the math can flip the other way against direct provider keys. Run the numbers before you migrate everything.

**Sandbox cold starts are real.** First execution of a runtime image is 600-900 ms. Subsequent executions in the same sandbox are sub-100 ms. If your agent calls a tool once per turn and turns are infrequent, you eat the cold start every time. The persistent pool is worth it when execution rate exceeds about 1 per minute per user.

**Flags evaluated client-side leak.** If you ship a [Next.js](/blog/nextjs-ai-app-stack-2026) page that reads a flag in the browser, the flag value is in the response. Use server-side evaluation for anything sensitive - model selection, tool gating, anything cost-related. The SDK supports both modes; pick the right one consciously.

**Microfrontends has the smallest agent story right now.** It is genuinely useful for partitioning team ownership of a UI but the "agent renders a fragment" use case is more hype than substance today. There is no first-class generative UI primitive in the announcement; you can build one on top, but you are building it.

## Where It Fits in the Agent Stack

The right way to read this announcement is as a redrawing of the seams. Vercel is saying: model calls go through Gateway, code goes through Sandbox, behavior is controlled by Flags, UI is composed by Microfrontends. Everything else - orchestration, memory, evals, observability - is left to other tools or to your application code.

That is a defensible split. Orchestration frameworks (LangGraph, Mastra, the AI SDK itself) sit on top of Gateway. Memory layers (Mem0, Letta, your own pgvector) live alongside. Evals (Braintrust, Langfuse) consume the gateway's request logs. The platform takes the parts that have to be infrastructure and leaves the parts that benefit from competition.

Where I think it gets interesting for indie devs is the MCP angle. The natural complement to AI Gateway is a hosted MCP server registry - a place where you publish tools your agents can use, with auth and rate limits and observability. That is exactly what we built [MCPaaS](https://mcpaas.developersdigest.tech) for: deploy an MCP server in one command, get a public endpoint, plug it into any agent runtime including Vercel's. The two stacks compose cleanly because Gateway treats MCP tools the same as any other tool call.

The other adjacent need is filesystem state for agents. Sandbox gives you ephemeral compute, but agents that work on files for hours need persistence and addressability. [AgentFS](https://agentfs.developersdigest.tech) is the DD product for that - a virtual filesystem with versioning that any sandbox or agent can mount. Vercel does not solve this problem and arguably should not; it is a different shape than what Sandbox is for.

I walked through the full stack composition on the [Developers Digest YouTube channel](https://youtube.com/@DevelopersDigest) including a live build of an agent that uses all four primitives plus an external MCP server.

## Wiring It Into a Real Product

A working pattern that has held up across three production agents I have shipped.

Define your model selection as a flag from day one. Even if you only have one model, wrap it. The day you want to A/B a new release or fail over to a cheaper model during a billing emergency you will be glad you did.

Treat Sandbox as the only place untrusted code runs, including code generated by your own agents. The temptation to "just eval this small Python snippet" in your Node process is the temptation that ends careers. The Sandbox primitive is cheap enough that there is no excuse.

Log every Gateway request to your own store, not just Vercel's. The gateway has good observability but vendor logs are not your logs. Pipe them into whatever you use for production telemetry. We pipe ours into a Postgres table partitioned by day and it is the single most useful debugging tool we have.

Use Flags for incident response, not just feature releases. When a model provider is degraded at 3am, the move is to flip a flag that routes around it, not to push a deploy. Build that muscle when nothing is on fire.

## What To Watch Next

The open question is whether Vercel adds an opinionated orchestration layer. Right now they are deliberately neutral - the AI SDK is provider-agnostic, the gateway is router-only, and the rest is up to you. That is the right call for adoption but it leaves a gap that someone will fill. Either Vercel ships a Mastra-style framework as a first-party product or a third party becomes the default on top of the stack.

The other thing to watch is pricing on Sandbox at scale. Microvm execution is genuinely expensive infrastructure. Either the price comes down as utilization improves or the high-volume case migrates to Modal, E2B, or self-hosted Firecracker. Vercel's bet is that the convenience of one platform will hold most workloads inside it.

Either way, the abstraction is now named. If you are designing an agent stack in 2026, these are the four boxes to start from. You can swap the implementations later. You cannot easily swap the architecture.



Vercel's New Durable Execution Programming Model: A Developer's Guide
Developers Digest — Wed, 29 Apr 2026 00:00:00 GMT

## The serverless agent problem, finally addressed

For three years now, every indie dev shipping an AI agent on Vercel has hit the same wall. Your function spins up, the agent calls a tool, the tool calls another tool, the loop ticks for ninety seconds, and then the runtime kills it. You retry. The model regenerates the same plan. You burn tokens. Your user waits.

For model-selection context, compare this with [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); the useful question is not only benchmark quality, but where the model fits in a real developer workflow.

Long-running agents have been a deploy nightmare on serverless. The mental model is wrong. A serverless function is a request handler. An agent is a process. The two have never fit together cleanly, and the workarounds - external queues, polling endpoints, status APIs cobbled together with KV stores - have all been variations of "rebuild a worker server, badly, in a serverless shape."

Vercel's [new programming model for durable execution](https://vercel.com/blog/a-new-programming-model-for-durable-execution) is the unlock. It is the first time the platform has shipped a primitive that maps cleanly onto the actual shape of an agent run. If you ship agents, this is the post you want to read this week.

## What the announcement actually says

Strip the marketing and the announcement is three things.

First, Vercel now supports durable functions as a first-class deployment target. A durable function looks like a regular async TypeScript function, but the runtime checkpoints its state at every `await` boundary. If the function gets killed - by timeout, by deploy, by infrastructure failure - it resumes from the last checkpoint instead of starting over. The state, including local variables, lives in Vercel-managed storage.

Second, the programming model is just JavaScript. There is no DSL, no graph builder, no YAML workflow definition. You write a function. You await steps. The runtime handles the rest. This is a meaningful difference from Inngest, Temporal, or AWS Step Functions, all of which require either a separate workflow definition or careful adherence to a step API.

Third, durable functions are integrated with Vercel's agent primitives, so streaming, tool calls, and the AI SDK plug in without ceremony. You can yield partial results to the client, persist progress to a durable store, and resume from a kill cleanly. The same function handles the user-facing stream and the long tail of tool calls that finish minutes later.

## What it looks like in code

Here is a minimal durable agent function. It plans a multi-step task, executes each step, and survives crashes between steps.

```typescript
import { durable, step } from "@vercel/functions/durable";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

export const POST = durable(async (req: Request) => {
  const { query } = await req.json();

  const plan = await step("plan", async () => {
    const { text } = await generateText({
      model: openai("gpt-5"),
      prompt: `Break this into 3 to 5 sub-tasks: ${query}`,
    });
    return text.split("\n").filter(Boolean);
  });

  const results: string[] = [];
  for (const [i, task] of plan.entries()) {
    const result = await step(`task-${i}`, async () => {
      const { text } = await generateText({
        model: openai("gpt-5"),
        tools: { search: webSearchTool },
        prompt: task,
      });
      return text;
    });
    results.push(result);
  }

  return Response.json({ plan, results });
});
```

Three things to notice.

The `step()` wrapper is the checkpoint boundary. Anything inside `step()` runs at most once per logical execution. If the function dies after `step("task-2")` and gets resumed, `task-0` and `task-1` come back from the durable log without re-running the model. You stop paying for the same tokens twice.

The function body reads top to bottom. There is no graph, no state machine, no callback chain. If you can read async TypeScript, you can read this. That is the dev ergonomics win.

The return value still streams. The runtime is smart enough to flush partial results to the client while the durable execution continues server-side. From the user's perspective, this is a normal API response. From your perspective, it is a process that can run for an hour without losing state.

## Gotchas, in order of how badly they will bite you

Step boundaries are sticky. Once you ship a step name, you cannot rename or remove it without breaking in-flight executions. Treat step names like database column names. Versioning the function helps, but design the step graph as if every name is permanent.

Non-determinism outside steps is a footgun. Anything outside `step()` runs every time the function resumes. If you call `Date.now()` in the function body, you get a different value every resume, which corrupts the state machine. Push every side effect, every clock read, every random number into a step. The rule is: if it would change between runs, it goes in a step.

Step output is serialized to JSON. You cannot return a class instance, a stream, or a function from a step. Plan your data model around plain objects. This catches teams accustomed to passing rich types around.

Local dev is the same model but the durability is in-memory. Crashes during dev do not resume the way production does. Test the resume path with the deploy preview, not just `vercel dev`.

## Where it fits the agent stack

The honest take. Durable execution on Vercel is not a replacement for a real workflow engine if your workload is heavy event sourcing, complex retries with backoff trees, or human-in-the-loop with weeks-long pauses. Temporal still wins those.

But for the 80 percent case - an agent that plans, calls four to twelve tools, occasionally takes ten minutes to finish, and needs to survive a deploy - this is exactly the right primitive. You do not stand up a separate worker, you do not pay for a queue, you do not write a status polling endpoint. You write the function and ship.

Compared to Inngest, Vercel's model is more locked-in but better integrated. Inngest gives you a richer event model and a separate dashboard, at the cost of running their SDK and their cloud. Vercel's durable functions are tied to Vercel's runtime, which is fine if you already deploy there.

Compared to AWS Step Functions, this is a different universe. Step Functions is a configuration language. Vercel durable execution is just code. If your team is allergic to Amazon's State Language, this is your migration path.

The deepest critique is portability. The moment your `step()` calls and resume semantics depend on Vercel's runtime, you are tied to Vercel. For most indie devs this is fine. For an enterprise team that may need to leave the platform, factor that into the architecture decision.

## Wiring it into a real product

We have been running durable execution against [Overnight](https://overnight.developersdigest.tech), our long-running task runner that lets you queue agent jobs and check back in the morning. The shape of the workload is exactly the shape Vercel optimized for: a queue of independent agent runs, each one ten to forty minutes of model calls and tool use, each one needs to survive infrastructure churn without losing token spend or partial outputs.

Before durable functions, the architecture was a separate worker process on Hetzner with a Postgres-backed queue. Cheap to run, fine to maintain, but it was a second deploy target with its own monitoring story. Moving the worker logic into durable functions collapsed two deploy units into one. The Postgres queue stayed - we still want a real queue for prioritization and rate limiting - but the worker that pulls a job and runs it is now a durable function on Vercel. Same cost ceiling, half the operational surface.

For a more orchestration-heavy workload, look at [Orchestrator](https://orchestrator.developersdigest.tech), our toolkit for chaining agent runs with shared context. Orchestrator is built around the idea that one agent run feeds the next, and the whole chain needs to be resumable. Durable execution as a primitive makes that pattern significantly easier to ship without rolling your own checkpoint storage.

The integration pattern that has worked best is: keep the queue and the human-facing API as regular handlers, push the agent loop itself into a durable function, and stream partial results back through a Convex-backed reactive channel so the client UI updates without polling. That gives you the best of both worlds - durable backend, reactive frontend, no homemade infrastructure.

## What to watch next

A few open questions are worth tracking.

Pricing at scale. Durable execution costs more per second than a regular function because of the checkpoint overhead. For short tasks the math is fine. For workloads that idle for hours waiting on external systems, the per-second cost can add up. Vercel has not published the [pricing](/blog/ai-coding-tools-pricing-2026) curve for very long-running durable functions yet, and the answer matters a lot for production economics.

Observability. The dashboard ships with a step-level timeline view, which is the right primitive. What is missing right now is a clean way to export step traces to OpenTelemetry or your own observability stack. If you already run Datadog or Honeycomb, plan on writing a forwarder for now.

Cold start on resume. There is real latency between "function got killed" and "function resumes from checkpoint." For interactive use cases this is fine - you tell the user the agent is working. For latency-sensitive flows, measure it and make sure it fits.

The bigger story to watch is whether other platforms follow. Cloudflare Workflows already exists in a more event-driven shape. AWS will eventually ship something competitive. The shape of durable execution as a deploy primitive is settling into a pattern, and once two or three platforms ship roughly compatible APIs, expect a portability layer to emerge.

We are doing a deeper hands-on walkthrough on the [Developers Digest YouTube channel](https://youtube.com/@DevelopersDigest) - building a durable agent from scratch, breaking it on purpose to show the resume path, and benchmarking it against a vanilla serverless implementation. If you ship agents on Vercel, the new programming model is worth an afternoon to internalize. The mental shift is small. The operational payoff is real.



Agent Replays with TraceTrail: Loom for Agent Runs
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The problem: agent runs are a black box

You give an [AI coding agent](/blog/what-is-an-ai-coding-agent-2026) a task. Twenty minutes later it comes back with a diff, a passing test, and a vague summary of what it did. If the diff is right, you ship it and move on. If something is off, you have a problem.

The actual run lives inside a transcript file somewhere on disk. For [Claude Code](/blog/what-is-claude-code-complete-guide-2026) that is a JSONL under `~/.claude/projects//.jsonl`. Hundreds of lines of message blocks, tool calls, tool results, and usage records. Readable, technically. Useful, not really.

So you do one of three bad things. You scroll the terminal scrollback until your eyes glaze over. You paste the JSONL into a chat window and ask another model to summarize it. Or you give up and re-run the task with extra logging, which means the original failure is now gone.

This is the gap. Agent runs have no shareable artifact. There is no link you can drop into a thread that says "here is exactly what the agent did, step by step, with the tool calls and the token spend, in a UI a human can scan in thirty seconds."

That is what TraceTrail is. The missing share link for AI coding agents.

## What TraceTrail does in one sentence

Upload an agent transcript. Get a public `/r/` URL. Anyone with the link can replay the run as a stepped timeline.

The mental model is Loom, but for agents instead of screen recordings. You ran something private. You want to show somebody what happened. You generate a link and paste it.

## Install and upload

TraceTrail is a [Next.js](/blog/nextjs-ai-app-stack-2026) app backed by Neon Postgres and Clerk. The MVP is intentionally small. Three routes, one parser, one timeline view.

If you are running it locally, the setup is the standard shape:

```bash
git clone 
cd tracetrail
pnpm install
cp .env.example .env.local   # fill in Clerk + DATABASE_URL
psql "$DATABASE_URL" -f drizzle/0000_initial.sql
pnpm dev
```

Open `http://localhost:3000`, sign in through Clerk, and you land on a single upload form. Drag a transcript onto it, or pick a file. The accepted shapes are:

- **Claude Code JSONL.** One JSON object per line, with `type`, `message.role`, and `message.content` blocks. This is the format Claude Code already writes to `~/.claude/projects/`.
- **JSON array.** A plain array of `{ role, content }` message objects. This is what most generic [agent frameworks](/blog/ai-agent-frameworks-compared) emit.
- **Single JSON object** with an `events: [...]` field. For frameworks that wrap their runs in metadata.

Behind the form is `POST /api/upload`. It is auth-gated: you have to be signed in to push a transcript. The endpoint returns `{ id, url }`. The `url` is your share link.

The replay route, `GET /r/[id]`, is public on purpose. Once a run is uploaded, anyone with the link can watch it. This is the Loom tradeoff. Public-by-default is the whole point of a share link. If a run contains anything sensitive, do not upload it. There is no redaction in the MVP and there is no delete UX yet either.

## What the share link reveals

The replay page is a stepped timeline. Each event in the transcript becomes one step. The parser at `src/lib/parse.ts` flattens the raw JSONL into four event kinds:

- **Messages.** User, assistant, or system text. The role is normalized so generic transcripts and Claude Code transcripts render identically.
- **Tool calls.** Each `tool_use` block becomes its own step, with the tool name and the input JSON. Bash commands, file reads, edits, web fetches, MCP calls. All of it.
- **Tool results.** The output that came back. Truncated to 8 KB per result so a single noisy `ls` does not balloon the page. Errors are flagged.
- **System events.** Init blocks, hook outputs, anything tagged `system`.

At the top of the page you get the totals: input tokens, output tokens, message count, tool call count. Token totals only show up when the source transcript actually included `usage.input_tokens` and `usage.output_tokens`. There is no tokenizer fallback. If your framework does not record usage, that section will be zeros, and that is honest.

The visual job of the timeline is just to make the run scannable. You should be able to skim the steps, see where the agent went off the rails, expand the tool result that matters, and close the tab. No video player to scrub through. No chat UI to scroll. Just a list of what happened, in order.

## Use cases

Once you have a share link primitive, a bunch of workflows that used to be painful become one paste.

**Debugging your own runs.** When a long agent run produces a wrong answer, you upload the JSONL and look for the moment things went sideways. Usually it is one bad tool result that the agent then built ten more steps on top of. Seeing the timeline at a glance is faster than `grep`-ing the JSONL.

**Onboarding teammates.** New person joins. You want to show them how Claude Code actually works in your repo. You drop three replay links into the onboarding doc: a clean run, a recovered run, a failed run. They scrub through in five minutes and get more context than an hour of pairing.

**Showing clients or stakeholders.** Non-engineers do not want to watch a screen recording of you typing. They want to see "the AI did these eight steps and produced this PR." A replay link is the right object for that conversation. It is also the right object to attach to a status update.

**Evaluating sub-agents.** If you run agent teams, you have N parallel runs per task. Having a stable URL per run lets you compare them the way you would compare videos in the [compare hub](/compare). Pick the cleanest run. Link it. Move on.

**Pairing with another agent.** Tools like [Promptlock](/blog/prompt-versioning-with-promptlock) version the prompts that go in. TraceTrail captures the runs that come out. Together they close a loop: you can change a prompt, replay the resulting agent run, link the replay back to the prompt version, and have a real audit trail.

## What TraceTrail is not yet

The MVP is deliberately narrow. A few things people will ask for that are not in this version:

- **No redaction.** The parser does not scan for secrets, file paths, or PII. Whatever is in your JSONL ends up on the public page. Treat the upload form like `gist.github.com`: only paste what you would paste into a public gist.
- **No delete UX.** There is no dashboard to list your uploads or revoke a link. The id is unguessable, but the design assumption is "public forever once uploaded."
- **No streaming uploads.** The `/api/upload` route buffers the whole file in memory with a 10 MB cap. Long agent runs in the tens of MB will fail. Chunked ingest is on the list.
- **No tokenizer fallback.** Token totals come from the transcript or they come back zero. No re-tokenization on the server.
- **No CLI uploader, no embeds, no R2 artifacts.** Web upload only, web replay only, in this version.

These are all known. The first version ships the share link primitive and nothing else, because the share link is the whole product.

## Try it

If you run any agent that writes a transcript to disk, you can use TraceTrail today. The fastest path is to grab one of your existing Claude Code session files, sign in, drag it onto the form, and paste the resulting URL into your team chat. That is the entire onboarding.

For deeper agent tooling, pair it with the patterns in [Prompt Versioning with Promptlock](/blog/prompt-versioning-with-promptlock) and the [compare hub](/compare). Versioned prompts on the way in. Replayable runs on the way out. Two share-link primitives that finally make agent work feel like normal software work.

> Screenshots TODO: upload form, replay timeline, tool call expanded view, totals header.



Best Claude Code Skills in 2026: A Curated Directory
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

If you have used [Claude Code](/blog/what-is-claude-code-complete-guide-2026) for more than a week, you have probably hit the wall. The base agent is sharp, but the second your work gets repetitive, you start writing the same context into the same prompts day after day. Skills are how you stop doing that.

A skill is a small folder of markdown and helper scripts that Claude Code loads on demand. The model decides when to pull it in based on a one-line description. You stop reprompting. You start composing. If you have not installed Claude Code yet, start with the [Getting Started guide](/guides/claude-code-getting-started).

The problem in 2026 is that the skills ecosystem has gone from empty to flooded in about six months. There is a lot of noise. This post is a working directory of skills I actually use, organized by category, with install paths and honest notes on what each one is good for. If you want the framing for why skills are eating prompt engineering, read [why skills beat prompts for coding agents in 2026](/blog/why-skills-beat-prompts-for-coding-agents-2026) first. For the prompts you still write by hand, our [prompt critic](/prompt-tester) will flag the usual failure modes before you paste.

## How to read this list

For each skill below you get:

- A one-line description of what it does
- The install command or repo path
- When it is worth loading
- When you should skip it

I am not going to pad this with twenty entries. The point of a skill directory is to filter. Eight to twelve well-chosen skills will cover most of a senior developer's day.

## 1. Documentation fetcher

**What it does:** Pulls current docs for any library, framework, or CLI tool before the model answers. Replaces the "let me just guess based on training data" failure mode.

**Install:**

```bash
mkdir -p ~/.claude/skills/find-docs
# Add a SKILL.md that wraps a doc-fetch CLI like ctx7
```

**When to load:** Any time you are working with a library that has shipped a major version in the last twelve months. Next.js, Prisma, the [Anthropic](/blog/anthropic-vs-openai-developer-experience) SDK, and most Vercel tooling have all moved fast enough that training data is unreliable.

**When to skip:** Pure refactoring inside your own codebase. Adds latency for no benefit.

## 2. Project rules and config updater

**What it does:** Edits `~/.claude/settings.json` and `.claude/settings.local.json` safely. Adds permissions, hooks, and env vars without you hand-editing JSON.

**Install:** Ships with Claude Code as `update-config`.

**When to load:** Anytime you say "from now on, every time X happens." That is a hook, not a memory note. The skill knows the difference.

**When to skip:** One-off settings like theme. Use the `/config` command.

## 3. Skill auditor

**What it does:** Lists every loaded skill, its token cost, and its last-used timestamp. Tells you which skills are burning context for no return.

**Install:**

```bash
git clone https://github.com/ ~/.claude/skills
# audit and prune skills ship together
```

**When to load:** Once a month. Skills bloat is silent. You will be shocked how many you stopped using.

**When to skip:** New machines with fewer than ten skills installed.

## 4. Web research and scraping

**What it does:** Wraps Firecrawl's search, scrape, map, crawl, and interact endpoints. The model picks the right tool for the job. You stop hand-writing fetch loops.

**Install:**

```bash
# The firecrawl skill bundle covers search, scrape, map, crawl, and interact
# Set FIRECRAWL_API_KEY in your shell
```

**When to load:** Any research task that touches the live web. Especially good for competitive analysis, doc archaeology, and pulling structured data out of marketing pages.

**When to skip:** Pure local-codebase work. The skill list gets noisy.

## 5. Multi-agent dispatch

**What it does:** Decomposes a goal into independent sub-tasks and fans them out to multiple agents in parallel. Cuts wall-clock time on research and audits by 3 to 5x.

**Install:** Available as the `swarm` and `multica-pipeline` skills in most curated bundles.

**When to load:** When you have a task with two or more independent parts. Three sequential searches are slower than three parallel agents. See the [agentic dev stack walkthrough](/blog/agentic-dev-stack-2026) for a full example.

**When to skip:** Strictly sequential work. A migration that has to land in order does not benefit from parallelism.

## 6. Deploy and infra debug

**What it does:** Encapsulates a specific deploy target's debugging playbook. Coolify, Vercel, Fly, Railway each have their own failure modes and the skill knows them.

**Install:**

```bash
# Example: a coolify-debug skill that knows about
# pnpm-lock drift, build cache pruning, and queue inspection
```

**When to load:** The first time a deploy goes red. The model goes from generic advice to running the actual recovery commands you have written down before.

**When to skip:** Local dev. Adds nothing until something is actually broken in production.

## 7. Claude API and SDK builder

**What it does:** Knows the current Anthropic SDK shape, including [prompt caching](/blog/prompt-caching-claude-api-production-guide), extended thinking, batch, files, and citations. Migrates code between Claude model versions automatically.

**Install:** Ships as `claude-api` in most curated skills bundles.

**When to load:** Any file that imports `anthropic` or `@anthropic-ai/sdk`. The skill triggers automatically once you have it installed.

**When to skip:** [OpenAI](/blog/openai-vs-anthropic-2026) or other-provider SDK code. The skill is provider-specific on purpose.

## 8. Site QA and improvement loop

**What it does:** Runs a structured audit of a site or app, writes findings into `QA.md`, then a sibling skill picks items off that list and fixes them.

**Install:** Project-local. Lives in `.claude/skills/qa` and `.claude/skills/improve`.

**When to load:** At the start of any session on a site you ship to real users. Catches design drift, dead links, and unused code before they pile up.

**When to skip:** Throwaway prototypes.

## 9. Content production for video and blog

**What it does:** A small bundle that handles research, scripting, blog drafting, distribution, and YouTube production assets for a faceless channel. The same pattern works for any content shop.

**Install:** Project-local skills under a namespace like `devdigest:*`.

**When to load:** When you are operating a content pipeline, not just writing one post. The skill enforces the linking and frontmatter conventions you have already decided on.

**When to skip:** A single one-off blog post. Just write it.

## 10. Skill builder

**What it does:** Generates new skills from a description. Asks the right questions about triggers, scope, and disclosure depth, then writes the SKILL.md and helper files.

**Install:** A meta-skill that ships in most curated bundles as `skill-builder` or similar.

**When to load:** The third time you find yourself reprompting the same context. That is the signal that you have a skill, not a prompt.

**When to skip:** First-time use. Read [what are Claude Code skills](/blog/what-are-claude-code-skills-beginner-guide) first.

## Build your own: the five-minute skill

The directory above is a starting point, not a destination. Most of the leverage comes from skills you write for your own workflow. Here is the shortest path.

Step one: notice the repetition. If you are pasting the same three paragraphs of context into Claude Code more than twice a week, you have a skill.

Step two: create the folder.

```bash
mkdir -p ~/.claude/skills/my-skill
cd ~/.claude/skills/my-skill
```

Step three: write `SKILL.md`. The frontmatter only needs a name and a description. The description is load-bearing because it is what Claude reads to decide whether to pull the skill into context.

```markdown
---
name: my-skill
description: One sentence that tells Claude when to load this. Be specific about triggers.
---

# My Skill

Body goes here. Progressively disclose: link to deeper docs only when needed.
```

Step four: keep the body small. Under 500 tokens for the always-loaded portion. Link out to longer reference files that the model can read on demand. The [self-improving skills](/blog/self-improving-skills-claude-code) post covers the disclosure pattern in depth.

Step five: test it. Open Claude Code, trigger the situation that should activate the skill, and watch whether it actually loads. If the model does not pick it up, your description is too vague. Rewrite it with concrete triggers like "when the user runs npm test" or "when a file imports stripe."

That is the whole loop. Notice, name, write, test, refine.

## Roadmap honesty

A few things this directory deliberately does not include yet.

**A hosted skills marketplace.** I am building one (see [Hookyard's tutorial flow](/apps) for the kind of in-product onboarding I want), but the truth is that for most developers in 2026, a curated GitHub repo plus a sync command is still the right install path. Marketplaces add discovery; they also add abandonware. I would rather link to ten skills I run every day than browse a thousand I do not.

**A pricing comparison for skills tools.** Skills themselves are free. The agents that run them are not. If you want to see how the underlying tools stack up, the [AI coding tools pricing comparison for 2026](/blog/ai-coding-tools-pricing-2026) and the [/compare page](/compare) are kept current.

**Anti-patterns.** I am collecting them, but the post is already long. The short version: do not write skills that try to do too many things, do not write skills with vague triggers, and do not write skills that duplicate what a well-named slash command would do better.

**Cross-agent skills.** Skills officially landed in Codex earlier this year, and the format is converging. For now, write skills for the agent you actually use the most. Portability is improving but is not free yet.

If you want the broader landscape of which agent to run those skills inside, the [10 best AI coding tools in 2026](/blog/best-ai-coding-tools-2026) post is the current reference.

## The point

Skills are not a productivity hack. They are the place where your taste, your defaults, and your project conventions live so that you stop typing them. Treat the directory above as a starting kit. Audit it monthly. Delete what you do not use. Write the ones that are missing.

The developers who will get the most out of Claude Code in 2026 are the ones who treat their skill folder like a dotfiles repo: small, opinionated, version-controlled, and always shrinking back toward the things that actually earn their keep.

## Frequently Asked Questions

### How many Claude Code skills should I install?

Eight to twelve well-chosen skills cover most of a senior developer's day. More than that and you start paying context tax - every loaded skill consumes tokens whether it helps or not. Run a skill audit monthly and delete anything you have not triggered in thirty days.

### Where do Claude Code skills live on disk?

Skills live in `~/.claude/skills/` for global skills that apply across all projects, or `.claude/skills/` in a project directory for project-specific skills. Each skill is a folder containing at minimum a `SKILL.md` file with frontmatter (name and description) and body content.

### How does Claude Code decide which skill to load?

Claude reads the one-line description in each skill's frontmatter and pattern-matches against your prompt. A vague description like "helps with code" will rarely trigger. A specific description like "when the user runs npm test and tests fail" will trigger reliably. The description is load-bearing.

### What is the difference between a skill and a slash command?

Slash commands are explicit - you type `/commit` and it runs. Skills are implicit - Claude decides to load them based on context. Use slash commands for actions you want to trigger manually. Use skills for context and knowledge you want Claude to pull in automatically when relevant.

### Can I use the same skills in Cursor or Codex?

Cursor does not use the Claude Code skills format. Codex adopted a similar skill system in 2026 and the formats are converging, but portability is not seamless yet. For now, write skills for the agent you use most. Cross-agent skill portability is improving but expect some manual conversion.

### How do I write a skill that improves itself?

Add a reflection hook that runs after the skill is invoked. The hook prompts Claude to evaluate whether the skill helped, and if not, suggests an edit to the SKILL.md. Store reflections in a learnings file that the skill reads on next load. See the [self-improving skills](/blog/self-improving-skills-claude-code) guide for the full pattern.

### What makes a skill different from just adding instructions to CLAUDE.md?

CLAUDE.md loads on every prompt. Skills load only when triggered. Put global rules in CLAUDE.md - things like "never commit .env files" or "use TypeScript strict mode." Put domain-specific workflows in skills - things like "how to debug Coolify deploys" or "how to draft a blog post for this site." Skills keep your always-on context lean.

### Are there any costs associated with skills?

Skills themselves are free - they are just markdown files on your disk. The cost comes from the agent that runs them. Claude Code bills based on token usage, so skills that load large context will increase your spend. Keep skill bodies under 500 tokens and link to longer reference files that Claude can read on demand.



An Agent SDK Triage Bot for Commercial Insurance Submissions
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Inbox That Eats Underwriters

A commercial underwriter at a mid-market property and casualty carrier opens around forty submissions a day. Each one arrives as an email with three to fifteen attachments: a broker cover letter, a five-year loss run, a SOV spreadsheet, an ACORD 125, an ACORD 140, sometimes a building inspection report, sometimes a PDF that is just a photo of a fax. The first job is not [pricing](/blog/ai-coding-tools-pricing-2026). The first job is deciding whether the submission is even quotable inside the carrier's appetite.

For the larger agent workflow map, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) and [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they give the architecture and implementation context this piece assumes.

Most carriers handle this with a junior underwriting assistant who does the same checks every time: is the named insured already a customer, is the SIC or NAICS in our appetite, are the loss runs current, does the SOV total match the cover letter, are any required forms missing. It is a thirty-minute job per submission that nobody enjoys and everybody does badly by 4pm. The agentic wedge is not "automate underwriting." That is regulated and mostly a bad idea. The wedge is "automate the triage memo," with a hard stop before any decision that affects price or binding.

## Why The Agent SDK And Not A Workflow Tool

You could build this in n8n or Power Automate. Many carriers tried. The reason it usually fails is that submissions are messy in long-tail ways. Brokers send the SOV embedded as an image inside a PDF. Loss runs come from twelve different carrier formats. The ACORD form has handwritten amendments in the margins. A rigid workflow handles 60% and dies on the rest. A [coding agent](/blog/what-is-an-ai-coding-agent-2026) with file system access, an LLM, and a skill library handles 90% and writes a clean note about the 10% it could not.

The Claude Agent SDK is the right tool because it gives you the same primitives [Claude Code](/blog/what-is-claude-code-complete-guide-2026) uses, programmatically: tool use, skills, hooks, MCP servers, transcript output. You wrap it in a job runner that pulls from a shared mailbox, and you get a triage bot that produces a memo per submission with full audit lineage.

## File Structure

```
submission-triage/
  src/
    index.ts                 # Agent SDK entry point
    runner.ts                # mailbox poller, queue, retry
    types.ts                 # Submission, Memo, AppetiteRule
  skills/
    parse-acord/
      SKILL.md
      scripts/extract.py     # uses pdfplumber + a labeled schema
    parse-loss-run/
      SKILL.md
      scripts/normalize.py   # carrier-specific adapters
    parse-sov/
      SKILL.md
      scripts/sov_to_csv.py
    appetite-check/
      SKILL.md
      rules.yaml             # appetite filters, owned by underwriting
  mcp/
    policy-admin.ts          # read-only PAS lookup
    naics-lookup.ts
  prompts/
    triage-memo.md
  hooks/
    redact-pii.sh            # PreToolUse, scrubs SSNs, EINs from transcripts
    no-bind.sh               # PostToolUse, blocks any write to PAS
  out/
    {submission-id}/
      memo.md
      lineage.jsonl
      attachments/
```

## The Skills

The four skills are the heart of the system. Each is a small SKILL.md plus a script. The agent picks them up automatically and the underwriting team can update `rules.yaml` without touching code.

`parse-acord` knows the ACORD 125 and 140 layouts and returns a JSON object with named insured, mailing address, FEIN, SIC, NAICS, requested coverages, and a confidence per field. It does not guess. If a field is unreadable, it returns null and a reason.

`parse-loss-run` is the messiest one. It has a small registry of carrier templates (Travelers, Hartford, Liberty, CNA, Chubb, the regional ones the carrier sees most) and a fallback prompt for unknown formats. Output is a normalized five-year frequency and severity table.

`parse-sov` extracts the schedule of values, totals it, and compares to the cover letter number. A mismatch over 5% is flagged.

`appetite-check` reads `rules.yaml`, which encodes the carrier's actual appetite: NAICS in/out lists, TIV bands, loss frequency thresholds, geographic exclusions. The output is a clean pass or a list of specific reasons for referral.

## The Triage Prompt

The prompt the agent runs per submission is short and constrained:

> You are a submission triage assistant. You do not make underwriting decisions. You produce a triage memo using only the skills available. For the submission in `inbox/{id}/`, run `parse-acord`, `parse-loss-run`, `parse-sov`, then `appetite-check`. Write `out/{id}/memo.md` using the template in `prompts/triage-memo.md`. If any skill returns low confidence, say so explicitly. Never write to the policy admin system. Never quote a premium.

The memo template is the artifact that matters. Underwriters review the memo, not the agent. A good memo has: insured snapshot, appetite verdict with cited rules, loss summary, missing-information list, and a recommendation queue (decline, refer to senior, ready to quote).

## The Hooks That Make Compliance Sleep

Two hooks carry the regulatory weight.

`redact-pii.sh` runs as a `PreToolUse` hook on every transcript write. It strips SSNs, EINs in non-allowed contexts, and any string that looks like a driver's license. This keeps the agent's transcripts safe to retain for the seven years your state DOI probably requires.

`no-bind.sh` runs as a `PostToolUse` hook and rejects any tool call that targets a write endpoint on the policy admin system MCP. The [MCP server](/blog/complete-guide-mcp-servers) itself is read-only, but the hook is a second layer. Auditors love a second layer.

A third optional hook ships transcripts to your SIEM in the same JSONL format you already use for human underwriter activity. From a SOC2 perspective the agent becomes just another principal with an audit trail.

## Realistic Risks

Three risks are worth naming.

Bias. If `rules.yaml` encodes a proxy for a protected class, the agent will faithfully reproduce that bias at scale. Mitigation: have a model-risk reviewer audit `rules.yaml` the same way they would audit a rating algorithm.

Hallucinated extraction. The agent might confidently report a TIV that is wrong because the SOV had a merged cell. Mitigation: the SOV-vs-cover-letter cross-check, and a hard rule that any TIV above a threshold gets human extraction regardless of confidence.

Drift. Brokers change their templates. Carriers acquire each other and rename their loss-run formats. Mitigation: a weekly job that flags any submission where more than two skills returned low confidence, and routes those to a "improve the skill" backlog.

## Minimal Next Step

You can stand up a useful version of this in an afternoon, against your own sample submissions, no PAS integration required.

1. `npm create @anthropic-ai/agent` and pick the TypeScript template
2. Drop ten anonymized PDF submissions into `inbox/`
3. Write `appetite-check/rules.yaml` with five real appetite rules from your underwriting guide
4. Implement `parse-acord` first, using `pdfplumber` and a single labeled example
5. Wire the triage prompt into `src/index.ts`
6. Run it against the ten submissions and read the memos

Two of the ten will be wrong in interesting ways. Those two are the spec for the next iteration. Show the other eight to an underwriter and watch what they do with the memo. The carriers that win the next decade are not the ones with the biggest underwriting teams. They are the ones whose teams stop reading PDFs and start reading memos.



Claude Code as an HL7 to FHIR Migration Agent for Hospitals
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Pipe That Will Not Die

Walk into any mid-sized hospital integration team in 2026 and you will still find HL7 v2 messages flowing over MLLP between an old Epic interface, a lab system from a vendor that was acquired twice, and a homegrown bed-management app that nobody wants to touch. The org has a five-year FHIR mandate, a Mirth or Rhapsody engine in the middle, and one or two analysts who can read pipe-and-hat encoding without flinching. Everything else is tribal knowledge written into channel filters and JavaScript transformers.

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

This is the kind of work that looks tedious from the outside and terrifying from the inside. A wrong field map can put an allergy on the wrong patient. A dropped segment can lose a discharge time. The reason these migrations stall is not that FHIR is hard. It is that the existing v2 messages encode twenty years of local conventions that the spec never had opinions about, and nobody has the bandwidth to chase them all down.

Agentic coding tools change the math. [Claude Code](/blog/what-is-claude-code-complete-guide-2026), scoped properly, is unusually good at this kind of grinding, well-bounded, high-context translation work. The trick is wiring it so it never sees PHI it should not see, never writes to a production interface engine, and always produces a diff that a human integrator can sign off on.

## The Wedge

The non-obvious wedge is not "use AI to write FHIR resources." Half the FHIR community has tried that and bounced off the spec. The wedge is "use a [coding agent](/blog/what-is-an-ai-coding-agent-2026) to migrate the transformer code, not the data." The transformer is just JavaScript or Python. The agent reads the v2 sample, reads the channel transformer, reads the FHIR profile the org has standardized on (US Core, Carin BB, Da Vinci, whatever), and proposes a new transformer plus a test fixture. PHI never leaves the synthetic-fixture loop. The output is a pull request, not a live deploy.

## File Structure

A workable repo for this looks like:

```
hl7-fhir-migration/
  CLAUDE.md
  channels/
    adt-a08-bedboard/
      v2-sample.hl7          # synthetic, Synthea-derived
      current-transformer.js # exported from Mirth
      target-profile.md      # which FHIR profile + must-support fields
      tests/
        encounter.expected.json
        patient.expected.json
  skills/
    fhir-validate/
      SKILL.md
      scripts/validate.sh    # wraps HAPI validator
    hl7-parse/
      SKILL.md
      scripts/parse.py       # uses python-hl7
  .claude/
    settings.json            # hooks, allowlist, deny PHI paths
  mcp/
    fhir-server.ts           # local HAPI FHIR proxy, MCP wrapper
```

The `CLAUDE.md` does the heavy lifting. It tells the agent the org's profile choices, the deterministic ID strategy (almost always a hash of MRN plus assigning authority), the timezone rules, and the list of fields the compliance team cares about most: allergies, medications, code status, advance directives. Everything else is "best effort, flag for review."

## Key Prompts

The prompt pattern that works is two-pass.

Pass one is discovery. You point Claude Code at one channel folder and ask:

> Read `v2-sample.hl7` and `current-transformer.js`. Produce a table of every v2 field the transformer touches, the FHIR resource and element it maps to under our `target-profile.md`, and a confidence score. Flag anything where the source field is being parsed with a regex or a custom date format. Do not write code yet.

Pass two is implementation, scoped to one resource at a time:

> Implement the Encounter mapping only. Write a new transformer in `channels/adt-a08-bedboard/transformer.ts`. For every must-support field in `target-profile.md`, write a passing test in `tests/encounter.expected.json`. Use the `fhir-validate` skill on the output. If validation fails, fix the transformer, not the expected fixture.

The reason to split is cost and review. Discovery passes are cheap and make the human-readable artifact that the integration analyst actually wants. Implementation passes are bigger but bounded.

## The MCP Server

The single highest-leverage piece of glue is a local FHIR MCP server. It wraps a HAPI FHIR validator running in Docker and exposes three tools: `validate_resource`, `search_profile`, and `diff_against_baseline`. The agent calls `validate_resource` on every artifact it produces and gets back the same OperationOutcome a human would see in HAPI. Because the server is local and the fixtures are synthetic, no PHI ever crosses a network boundary.

A minimal server in TypeScript is around 120 lines using the official MCP SDK. It runs as a stdio child process of Claude Code, started from `.mcp.json`. The same server doubles as a skill backend if you prefer SKILL.md style invocations.

## The Hook That Makes It Safe

The non-negotiable piece is a `PreToolUse` hook in `.claude/settings.json` that blocks any read of files matching real PHI patterns. It looks for the org's MRN format, the v2 magic numbers in non-fixture directories, and any path under `production/`. If the agent tries to read a file outside `channels/*/` or the synthetic fixtures, the hook exits non-zero and Claude Code refuses the tool call.

A second hook on `PostToolUse` runs `git diff --stat` after every Write and rejects diffs that touch the production Mirth export directory. Belt and suspenders, but in healthcare you wear both.

## Risks and Guardrails

The honest risks are these. First, synthetic data does not capture every local convention. Synthea will not produce the OBX-5 quirks a particular lab uses. Mitigation: keep a "weird messages" library, scrubbed and de-identified by a human, that the agent can train its mappings against. Second, FHIR profiles drift. US Core 7.0 broke things US Core 6.1 allowed. Pin the profile version in `CLAUDE.md` and bump deliberately. Third, audit. Anything the agent touches needs a paper trail that a HIPAA auditor can read. The PR-only output, combined with hook logs written to an append-only file, satisfies most audit asks.

SOC2 and HITRUST add one more requirement: the agent's transcripts themselves are records. Claude Code's `--output-format jsonl` plus a hook that ships transcripts to your existing SIEM closes that gap.

## Minimal Next Step

You can run the smallest version of this today, before talking to compliance, on synthetic data only.

1. `mkdir hl7-fhir-migration && cd hl7-fhir-migration`
2. Drop a Synthea-generated ADT^A08 message into `channels/adt-a08-bedboard/v2-sample.hl7`
3. Paste any open-source Mirth transformer from GitHub into `current-transformer.js`
4. Write a six-line `CLAUDE.md` that names US Core 7.0 as the target profile
5. Run `claude` and paste the discovery prompt above

You will get back a field-by-field mapping table in about ninety seconds. That table, on its own, is more documentation than most channels have today. Show it to the integration lead. The conversation about whether to let an agent write the next transformer goes very differently once they have read the first one.

The hospitals that win the FHIR transition will not be the ones with the biggest integration teams. They will be the ones whose teams stop hand-typing transformers and start reviewing them.



Claude Code Hooks with Hookyard: npm install for Hooks
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The problem: hooks are powerful, discovery is broken

[Claude Code hooks](/blog/claude-code-hooks-explained) are one of the most underused features in the entire agent stack. They are shell commands that fire on lifecycle events. PreToolUse fires before a tool runs and can block it. PostToolUse fires after. UserPromptSubmit fires before your prompt reaches the model. Stop fires when the agent finishes a turn. SubagentStop fires when a spawned subagent wraps. Notification fires when Claude needs your attention.

That is the whole API. Six events, a JSON config, any shell command you want.

You can do real things with this. You can block `rm -rf` before it runs. You can auto-commit your Obsidian vault on every edit. You can pipe a one-line summary to a TTS engine when the agent finishes. You can log token spend per subagent. You can redact API keys from prompts before they leave your machine. None of this needs a plugin system. It is just shell on a tool event.

So why is nobody running hooks? Because installing one is a manual JSON-paste exercise.

The flow today looks like this. You read a blog post or a Discord message that has a useful hook. You open `~/.claude/settings.json`. You eyeball whether `hooks.PostToolUse` already exists. You merge the new hook block into the array, hoping you do not break the existing JSON. You save. You restart [Claude Code](/blog/what-is-claude-code-complete-guide-2026) and pray. If it does not work, you cannot tell whether your matcher regex is wrong, your shell command is missing, or you fat-fingered a comma.

There is no install command. There is no list of hooks. There is no way to tell what you already have running. Compare that to npm, where every dependency is one command and one entry in a manifest.

Hookyard is the fix. A curated directory of Claude Code hooks plus a CLI that patches your settings file safely. npm install for hooks.

## What ships in v0

Hookyard is two things in one repo.

A **[Next.js](/blog/nextjs-ai-app-stack-2026) directory site** where you browse hooks, filter by event, and copy the JSON snippet for any of them. Useful when you want to see what is out there or grab a single hook for a settings file you maintain by hand.

A **CLI** that does the actual install. `npx hookyard install ` reads the curated manifest, looks up the hook, opens `~/.claude/settings.json`, merges the hook block into the right event array, writes a `.bak` snapshot of the previous file next to it, and writes the new settings. It is idempotent. Run it twice and the second run prints `already installed` instead of duplicating the entry. Run `remove` to take it back out.

The manifest today has ten curated hooks across the event types that matter. A few real ones derived from the DD skill stack, a few illustrative entries flagged with `demo: true` so you know the shell command is a stub.

## Five hooks worth installing tonight

These are the entries from the manifest that I would actually wire up on a fresh machine.

**Block rm -rf.** A PreToolUse guard on `Bash`. Reads the tool input as JSON from stdin, regexes the command for `rm -rf` against `/`, `$HOME`, or `~`, and exits with code 2 to refuse the call. The whole hook is a single inline node script. If you have ever lost a directory to an over-eager agent, this is the cheapest insurance you will ever buy.

```json
{
  "event": "PreToolUse",
  "matcher": "Bash",
  "command": "node -e \"const i=JSON.parse(require('fs').readFileSync(0,'utf8'));const c=i.tool_input?.command||'';if(/rm\\s+-rf?\\s+(\\/|\\$HOME|~)/.test(c)){console.error('blocked');process.exit(2)}\""
}
```

**Obsidian Auto-Commit.** PostToolUse on `Write|Edit|MultiEdit|NotebookEdit`. Calls a shell script in `~/.claude/hooks/` that stages and commits the vault. Result: a per-edit git history of your notes, free, with no extra prompting. You can scrub through what the agent did to your second brain with `git log -p`.

**Track Skill Usage.** PostToolUse on `Skill`. Increments a counter in `~/.claude/skills/usage.json` every time a skill is invoked. After a week you have honest data on which skills earn their keep and which to prune. This is the same telemetry hook that powers the `/prune` workflow.

**Prompt Redactor.** UserPromptSubmit. Pipes your prompt through a redaction script that masks high-entropy strings and email addresses before the prompt is sent. Cheap privacy win. Marked `demo` in the manifest because the redaction shell script is yours to write, but the wiring works.

**Subagent Cost Log.** SubagentStop. Appends a timestamp and approximate spend to `~/.claude/cost.log` every time a spawned subagent finishes. If you run agent teams via the `/swarm` pattern, this is how you actually answer the "what did that fan-out cost" question without scrolling a transcript. Pairs naturally with [TraceTrail](/blog/agent-replays-with-tracetrail) for the per-run breakdown.

The manifest also includes Speech Summary on Stop, Run Tests on Edit, Lint on Edit, Desktop Notify, and Git Status on Stop. All ten render on the directory site with copyable JSON.

## Install flow, end to end

The CLI is one file. Three commands.

```bash
# See the catalog
npx hookyard list

# Dry-run into a fixture (does not touch your real settings)
npx hookyard install obsidian-auto-commit --settings /tmp/settings.json
cat /tmp/settings.json

# Install for real
npx hookyard install obsidian-auto-commit

# Take it back out
npx hookyard remove obsidian-auto-commit
```

Behind the scenes the install path does five things in order. It reads `~/.claude/settings.json` if it exists, or starts with `{}`. It looks the slug up in the manifest. It checks whether the hook is already installed by matching on `event + matcher + command`. If it is, it prints and exits. If not, it merges the hook into `settings.hooks[event]`, creating the array if needed. It writes a timestamped `.bak` next to the settings file. Then it writes the new JSON.

The `--settings` flag points the whole flow at any path. That is how the test suite works. Fixtures in `/tmp`, never your real config. The `--manifest URL` flag is also wired. Today the CLI imports the manifest directly from the package, but once the directory site is live, you point the CLI at `https://hookyard.dev/api/manifest.json` and you get the latest catalog without an `npm update`.

The whole thing is around 100 lines of TypeScript. There is nothing magic. The reason it feels like a product is that nobody else has bothered to ship the boring wrapper around `JSON.parse`, `merge`, `JSON.stringify`.

## Build your own hook in ten minutes

The fastest way to understand the system is to write one. Here is the loop.

Pick an event. PostToolUse with a matcher of `Bash` is a good starting point. It fires after every shell call the agent makes.

Write a shell command. The hook receives the tool input on stdin as JSON. For PostToolUse you also get the output. A trivial first hook just appends to a log:

```bash
mkdir -p ~/.claude/hooks
cat > ~/.claude/hooks/log-bash.sh <<'SH'
#!/usr/bin/env bash
jq -r '.tool_input.command' >> ~/.claude/bash.log
SH
chmod +x ~/.claude/hooks/log-bash.sh
```

Add it to your settings. The shape is fixed:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "$HOME/.claude/hooks/log-bash.sh" }
        ]
      }
    ]
  }
}
```

Trigger it. Ask Claude to run any shell command. Tail the log:

```bash
tail -f ~/.claude/bash.log
```

That is the entire model. Once you have one working hook, every other hook is the same shape with a different event, a different matcher, and a different shell command. The Hookyard manifest is just a catalog of useful instances of that shape.

When you have one you like, the next step is contributing it. That part is honest about where it stands.

## Roadmap honesty

v0 is deliberately narrow. There are real things missing.

There is **no in-browser Hook Builder yet**. You write hooks in your editor and add them to the manifest by hand. An authoring UI on the directory site is on the list but not in this version.

There is **no submit-a-hook flow**. The manifest is a TypeScript file in the repo. Community contributions today mean a PR against `lib/hooks-data.ts`. A web submit form with moderation comes later.

There are **no ratings, no installs counter, no paid hooks, no auth**. Clerk and Neon are stubbed for the version that introduces accounts. v0 is anonymous browse plus anonymous CLI install.

The **manifest is bundled with the CLI**. The `--manifest URL` flag is wired but the hosted manifest endpoint goes live with the production deploy of the directory site, not before.

The shape of v1 is clear. Authoring UI on the site, web submit flow, hosted manifest, install counts so you can sort by popularity, accounts so authors can update their own entries. None of that ships tonight. What ships tonight is the install primitive, because the install primitive is the whole product.

## Try it

If you have ever copy-pasted a hook from a blog post into `settings.json` and held your breath, this is for you.

```bash
npx hookyard list
npx hookyard install block-rm-rf
```

Your settings file gets a `.bak` snapshot, your agent gets a guard against the worst Bash command in computing, and you spent zero seconds editing JSON.

For the rest of the agent tooling stack, pair this with [Promptlock](/blog/prompt-versioning-with-promptlock) for prompt versioning on the way in, and [TraceTrail](/blog/agent-replays-with-tracetrail) for replayable runs on the way out. Versioned prompts, guarded tools, replayable runs. Three small share-link primitives that finally make agent work feel like normal software work. The full lineup lives on the [compare hub](/compare).

> Screenshots TODO: directory home, hook detail with copy button, CLI install in action.



Skills Marketplace: 312 Claude Code Skills, Curated
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The skill discovery problem nobody is talking about

[Claude Code skills](/blog/why-skills-beat-prompts-for-coding-agents-2026) are good. The discovery story for them is not.

If you have spent any time in the ecosystem this year, you know the loop. Someone posts a skill in a Discord. Someone else screenshots it into an X thread. A third person forks a gist, renames it, and pushes a slightly different version to their dotfiles. By the time you find the skill you actually want, you are reading a six-month-old README that references a deprecated SDK version and a hook format that changed two minor releases ago.

There is no canonical index. There is no version pinning. There is no signal for which skills are maintained, which are abandoned, and which are just somebody's afternoon experiment that got 80 stars and never shipped a v1.

We have been collecting skills internally for the [DD app portfolio](/apps) for about a year. The internal index started as a flat JSON file. It became a search UI. It became a thing other people wanted access to. So we shipped it.

Skills Marketplace is live. 312 skills indexed at launch. Curated, versioned, searchable, and free to browse.

## What is in the directory

The 312 skills at launch are everything we could verify works against the current [Claude Code](/blog/what-is-claude-code-complete-guide-2026) release. That number is the result of ingesting a much larger pile and dropping anything that failed our smoke test.

The directory breaks skills into the categories we actually use:

**Engineering** is the biggest bucket. Code review skills, refactor skills, test generation, security audit, dependency triage, migration helpers. If you have ever wanted a skill that does the boring half of a PR before you read the diff, this is where to look.

**Content and marketing** is the second-biggest. Blog drafting, video script outlining, distribution pack generation, newsletter drafts, social copy. We use most of these on this site daily.

**Workflow and ops** covers the meta-skills. Schedulers, loops, handoff generators, prune tools for archiving stale skills, audit tools that count tokens across your install. Less glamorous, more load-bearing than people give them credit for.

**Domain-specific** is everything else. Browser automation, scraping pipelines, image generation, audio transcription, vault management for Obsidian users, deploy helpers for Coolify and Vercel. Long tail by design.

Every skill page has the same shape. Description. Trigger phrases. Required tools and permissions. Last-updated date. Source repo. Install command. A version selector if the skill has tagged releases. A small graph showing install count over the last 30 days for skills that opted into telemetry.

Search is fast because the index is small and pre-built. Filters stack. You can ask for engineering skills updated in the last 14 days, with no [MCP](/blog/what-is-mcp) dependencies, that work on the current Claude Code version, and get a result list in under 200ms.

## Skills Pro: the part for authors

Browsing is free and stays free. The paid tier is for people who write skills and want to treat that as a real activity instead of a hobby.

Skills Pro gives authors an actual dashboard. You see install counts per skill, per version, per day. You see which trigger phrases are firing in the wild and which ones nobody uses. You see the geographic split if you care about it. You see version adoption curves so you know when it is safe to deprecate v1.

There is a verified-author badge. The verification flow is light: confirm a GitHub identity, point at a repo, sign one commit. The badge is not a quality signal, it is an identity signal. It tells installers that the skill they are about to drop into their global config came from the person they think it came from.

Pro authors get version pinning that actually works. Push a new version, mark it stable, and existing installers get an update prompt instead of a silent overwrite. Roll back from the dashboard if the new version breaks. We learned this one the hard way shipping our own skills.

There is a private skills tier for teams who want to share internal skills across a team without making them public. Same install flow, same version model, just gated to a workspace. This is the part that pays for the rest.

## Submitting a skill

The submission flow is the thing we spent the most design time on, because the failure mode for marketplaces is always "the submission queue is a graveyard and nothing ships."

Submit a skill at `/submit`. Paste a GitHub URL. The form pulls metadata, runs a static lint pass on the SKILL.md frontmatter, and shows you a preview of how the directory page will render before you commit to publishing. If the lint fails, it tells you exactly which field is wrong and links to the spec.

After preview, the skill enters a review queue. Review is currently human, currently us, currently fast. Median review time at launch is under 24 hours. We are not gatekeeping on quality, we are gatekeeping on "does this skill do what its description says." The bar is low and clear.

Once approved, the skill is live and the author gets an authorship record they can claim with a verified-author flow later. If you submitted skills before the verified-author flow existed, you can retroactively claim them by signing a commit on the source repo.

If you have written a tutorial showing how to build a skill, point at it from the submission. We highlight skills that come with real tutorials. Two examples worth reading: the [Hookyard tutorial on shipping hook-based skills](/blog/claude-code-hooks-with-hookyard) and the [SkillForge build log](/blog/skillforge-ci-and-cost-tape) from earlier this month. Both walk through a real skill from idea to publish.

## Roadmap

The launch directory is the floor, not the ceiling.

**Community curation.** Right now review is centralized. The plan is to move to a trust-graded curator model where established authors can approve submissions in their category. The infrastructure for that is half-built, the policy questions are still open. Expect this in the next 60 days.

**Paid skill marketplace.** Some skills are worth paying for. A skill that wraps a non-trivial pipeline, ships with hosted infrastructure, or includes a dataset belongs behind a price tag. We are building a Stripe-backed transactions layer with revenue split for authors. Free skills stay free, paid skills are opt-in only, and the directory will always show free alternatives next to paid ones so the comparison is honest.

**Skill bundles.** Most people do not install one skill, they install a stack. Bundles let an author or curator group skills into a starter pack, version it, and let installers pull the whole thing. Useful for onboarding, useful for opinionated workflows, useful for the [agentfs filesystem-as-skills pattern we wrote up last week](/blog/introducing-agentfs).

**Cross-tool indexing.** Skills are a Claude Code concept today, but the same metadata model fits Codex prompts, Cursor rules, and Augment commands. The directory will eventually index across all of them with a clear filter, so you can see the full landscape and not just the Claude slice. If you want a head-to-head view of the underlying tools, the [comparison page](/compare) covers that.

**Telemetry the user controls.** Install counts are opt-in. We are adding finer-grained controls so authors can request specific telemetry and installers can grant or deny it per skill. The default will always be off.

## Honest constraints

A few things the launch directory does not do, in case you came in expecting them.

It does not run skills in a sandbox. The directory hosts metadata, not execution. When you install a skill, it lands in your local Claude config and runs with whatever permissions you give it. Read the SKILL.md before you install. The verified-author badge is not a substitute for that.

It does not currently dedupe forks. If somebody forks a popular skill and republishes it under a different slug, you will see both. We have a clustering plan but it is not in the launch build.

It does not solve the "skill conflicts with another skill" problem. Two skills can claim the same trigger phrase, and Claude Code picks one with rules that are not always obvious. The directory shows trigger phrases on every page so you can spot a conflict before installing, but the resolution is on you.

It does not have a real moderation policy yet. We have an acceptable-use list and we will reject skills that exfiltrate data, ship malware, or scrape protected APIs. The full policy will land before we open community curation, because community curation without a clear policy is how you end up with a marketplace nobody trusts.

It is a directory. The hard parts of the skill ecosystem (versioning at scale, signed manifests, deterministic installs, conflict resolution) are still hard. We are not pretending to have solved them. We are pretending to have indexed the ones that exist so you can find them faster.

## Try it

The directory is live. Browse 312 skills, filter by category, install with one command. If you write skills, the Pro tier is open for early access. If you have a skill we missed, submit it and we will review within a day.

The whole point of skills is that the boring parts of the work get cheaper every week. A directory of 312 of them, with version pinning and an honest submission flow, is the smallest thing we could ship that makes that compounding go faster.

That is the bet.

---

## Frequently Asked Questions

### What is the Skills Marketplace?

The Skills Marketplace is a curated directory of Claude Code skills - reusable capability files that extend what Claude Code can do. It indexes 312 verified skills at launch, organized by category (engineering, content, workflow, domain-specific), with search, version pinning, and install-count analytics. Free to browse, with a Pro tier for skill authors who want dashboards and verified badges.

### How do I install a skill from the marketplace?

Every skill page shows an install command you can copy and run. Skills land in your local Claude config folder (typically `~/.claude/skills/`) and work the next time you start Claude Code. The install is a one-liner, but always read the SKILL.md before installing - the marketplace is a directory, not a sandbox.

### What does Skills Pro include for authors?

Skills Pro gives authors a dashboard with install counts per skill, per version, per day. You see which trigger phrases fire in the wild, geographic distribution, and version adoption curves. There is a verified-author badge (GitHub identity confirmation), working version pinning with rollback, and a private skills tier for teams who want internal skills without making them public.

### How do I submit a skill to the marketplace?

Submit at the `/submit` page by pasting a GitHub URL. The form pulls metadata, runs a lint pass on the SKILL.md frontmatter, and shows a preview before publishing. After submission, the skill enters a human review queue - median review time is under 24 hours. The bar is low: "does this skill do what its description says."

### Is the Skills Marketplace free?

Browsing and installing skills is free and stays free. The paid tier (Skills Pro) is for authors who write skills and want analytics, verified badges, version pinning, and private team skills. The paid tier funds the infrastructure; the free tier is the core product.

### Does the marketplace sandbox or verify skill safety?

No. The marketplace hosts metadata, not execution. When you install a skill, it runs with whatever permissions you give Claude Code. The verified-author badge confirms identity (this skill came from the GitHub account it claims), not quality or safety. Read the SKILL.md before installing any skill from any source.

### What categories of skills are in the marketplace?

The launch index covers four main categories. Engineering is the biggest - code review, refactoring, test generation, security audit, migration helpers. Content and marketing is second - blog drafting, video scripts, distribution packs, social copy. Workflow and ops covers schedulers, loops, handoffs, pruning, and audit tools. Domain-specific is the long tail - browser automation, scraping, image generation, audio transcription, vault management, deploy helpers.

### What is coming next for the Skills Marketplace?

The roadmap includes community curation (trusted authors can approve submissions), a paid skill marketplace (Stripe-backed with author revenue share), skill bundles (install a whole stack at once), cross-tool indexing (skills, Codex prompts, Cursor rules, Augment commands in one directory), and user-controlled telemetry with finer-grained permissions.



Codex CLI Hooks for PLC and IoT Firmware Review on the Factory Floor
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Code Review That Never Happens

Walk into the controls room of a mid-sized contract manufacturer and you will find a Rockwell PLC running ladder logic that was last edited in 2019, an ESP32 fleet on the line collecting torque data over MQTT, and a single controls engineer who knows where every change came from. There is no pull request. There is no diff review. There is a backup `.ACD` file with last week's date and a sticky note on the HMI that says "do not change setpoint."

For broader context, pair this with [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); those companion pieces show where this fits in the wider AI developer workflow. This use case is also a concrete example of [Codex expanding into general-purpose work](/blog/codex-general-purpose-ai-agent) - operational tasks with files, tools, review loops, and artifacts that are not traditional software development.

This is not negligence. It is the reality of OT versus IT. The controls engineer is also the network admin, the mechanical fixer, and on bad days the forklift driver. Code review is an IT ritual that never made the trip across the air gap. The cost is real. A bad rung edit can scrap a shift's worth of parts. A bad ESP32 firmware push can put a forklift sensor into a reboot loop and stop the line for an hour. Insurance and ISO 27001 auditors are starting to ask pointed questions, and nobody has a good answer.

The agentic wedge here is small but unusually high leverage. A [coding agent](/blog/what-is-an-ai-coding-agent-2026) will not write your ladder logic. It should not. But it can absolutely review a diff against a checklist, flag the patterns that have historically caused outages, and produce a one-page change record that the engineer signs before the push. Codex CLI, with the right hooks, is a near-perfect tool for this.

## Why Codex CLI

Three reasons. First, controls shops live in a Windows plus a few Linux jump boxes and Codex CLI installs cleanly on both with no SaaS dependency. Second, the OT network is segmented and the agent can run entirely on a local jump box with the model called over a single egress hole, which the IT team can audit. Third, Codex CLI's hook model lets you bolt deterministic checks around the LLM in a way that satisfies the part of the engineer's brain that does not trust language models around safety-rated code.

You are not using the agent to be smart. You are using it to be tireless and consistent.

## File Structure

```
controls-review/
  CLAUDE.md                # used by codex too via --instructions
  AGENTS.md                # codex-native instructions
  exports/
    line-3-packer/
      current.L5X          # exported from Studio 5000
      previous.L5X         # last known good
      diff.txt             # generated, plain-text rung diff
  firmware/
    torque-sensor/
      src/                 # PlatformIO ESP32 project
      build/firmware.bin
      manifest.json        # signed build metadata
  checklists/
    plc-review.md
    firmware-review.md
    safety-rated.md
  hooks/
    pre-review.sh          # runs L5X-to-text diff before any LLM call
    post-review.sh          # writes the change record, blocks if missing fields
    deny-write.sh           # blocks any tool call that writes to exports/
  records/
    {date}-{line}-{change-id}.md
```

The PLC project is checked into a private Gitea on the jump box. Studio 5000 exports `.L5X` (XML) which is reviewable by a text agent in a way `.ACD` (binary) is not. The firmware project is a normal PlatformIO repo. Both feed the same review pipeline.

## The Checklists Are The Product

The single most valuable artifact in this whole setup is `checklists/plc-review.md`. It is the controls engineer's accumulated wisdom written down for the first time. A real one looks like:

- Any new OTE on a safety-rated output is a hard stop. Refer to safety engineer.
- Any timer preset under 50 ms in the packer subroutine. The actuators cannot keep up.
- Any change to a rung that references `Recipe_Active`. Recipe edits go through the recipe manager, not ladder.
- Any new tag in the `_Internal` scope that is also referenced by the HMI. Naming collision.
- Any change to E-stop reset logic. Hard stop, requires sign-off.

The checklist is a living document. Every time something breaks on the line, a new line is added. The agent reads it on every review.

## The Review Prompt

The prompt fits on a sticky note:

> Read `exports/{line}/diff.txt`. Read `checklists/plc-review.md`. Produce a review note in `records/`. Use the template in `checklists/template.md`. For each rung that changed, list the checklist items it triggers, the risk level, and the question the engineer should ask before approving. Do not suggest code changes. Do not approve.

The "do not approve" line is load bearing. The agent's job is to surface, not to bless. The signature on the change record is human.

## The Hooks

`pre-review.sh` runs before any LLM call. It uses a small XSLT transform to flatten the L5X into rung-by-rung text, then `git diff --no-index` against the previous export. If the diff is empty, the hook exits 0 and the review skips. If the diff is over a configured size (say 200 rungs), the hook exits non-zero with a message asking the engineer to break the change into smaller pieces. This single hook prevents 80% of the failure mode where a controls engineer "cleans up" a routine and ships a 1500-line diff nobody can review.

`deny-write.sh` is a `PreToolUse` hook that blocks any tool call that would write into `exports/` or `firmware/build/`. The agent cannot modify the artifact under review. Belt and suspenders.

`post-review.sh` runs after the agent writes the record. It validates that the record has all required fields: change ID, line, requestor, checklist hits, risk level, sign-off line. If any are missing, the hook deletes the record and exits non-zero so the agent has to retry. This forces the agent to produce a record that an auditor will accept.

## Risks And Guardrails

Three risks worth naming.

Air gap. Many controls networks genuinely cannot reach a hosted model. Solutions: run the model locally on a small GPU box on the OT side, or batch reviews to a jump box on the corporate network and bring records back via a one-way file transfer. Codex CLI works fine in either mode.

Safety-rated code. Anything tied to an SIL-rated function should bypass the agent entirely and go straight to the safety engineer. The checklist enforces this with a hard-stop rule. Do not soften it.

Over-reliance. The agent's review is a checklist run, not a substitute for engineering judgment. The signed record should make this explicit with a line that says exactly that. Auditors prefer it. Engineers prefer it. The risk is real and naming it is most of the mitigation.

The firmware side has its own risks. ESP32 OTA updates can brick a device if the partition table is wrong. The firmware checklist includes a partition-table diff check and a rollback-image check. Both are deterministic and run as hooks, not as LLM prompts.

## Minimal Next Step

This one is genuinely doable in an afternoon, on your own machine, with a single PLC export.

1. Install Codex CLI on the jump box. Confirm it can reach the model endpoint through whatever proxy the IT team requires.
2. Export two versions of one routine from Studio 5000 as `.L5X` files. Drop them in `exports/line-3-packer/`.
3. Write `checklists/plc-review.md` with five real rules from your last five outages.
4. Wire `pre-review.sh` to flatten and diff the L5X files.
5. Run `codex` and paste the review prompt.

You will get back a one-page review note that flags real issues. Show it to the controls engineer. The conversation about whether to require this on every change goes very differently after the first time it catches something they would have missed at 4pm on a Friday.

The shops that will pass the next round of cyber and quality audits are the ones whose change records are written, signed, and searchable. Agents are the cheapest way to get there.



Codex vs Claude Code in April 2026: Which Agent for Which Job
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## Two agents, two philosophies

In April 2026, the terminal-agent question is no longer "which CLI is more capable." Both [Claude Code](/blog/what-is-claude-code-complete-guide-2026) and Codex are competent enough to ship real production work in real repos. The question now is which one fits which job - because the two products have visibly diverged.

Claude Code optimizes for **extensibility on top of a planning model**. Opus 4.7 is the thinking head; skills, sub-agents, hooks, [MCP servers](/blog/complete-guide-mcp-servers), and plugins are the body. The bet is that you will want to bend the agent to your repo and your team.

Codex optimizes for **a tightly integrated agent loop with strong defaults**. GPT-5.5, the rebuilt [Codex CLI](/blog/openai-codex-guide), the new app-server, the in-app browser, and the automatic reviewer are designed to behave well out of the box without much customization.

Both bets are reasonable. They lead to different daily ergonomics.

If your main question is longer-running work, the sharper follow-up is [Codex `/goal` vs Claude Managed Outcomes](/blog/codex-goal-vs-claude-managed-outcomes-practical-differences): Codex is moving toward persistent execution loops, while Claude's managed-agent outcomes are moving toward rubric-graded task closure.

## TL;DR decision path

- Want the fastest side-by-side verdict? Use the dedicated [Claude Code vs Codex comparison page](/compare/claude-code-vs-codex).
- Want cost to be the deciding factor? Start with the [pricing hub](/pricing) and the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison).
- Want the April 2026 changes and command details? Read the [Codex changelog analysis](/blog/codex-changelog-april-2026) and the [OpenAI Codex guide](/blog/openai-codex-guide).

## What changed in the last 30 days

A quick state-of-the-world before the verdict, because anything older than April is already stale.

**Anthropic** released [Claude Opus 4.7](https://www.anthropic.com/news/claude-opus-4-7) on April 16. Roughly 13% better than Opus 4.6 on a 93-task internal coding benchmark, with stronger vision and noticeably more taste on UI and document tasks. The [official Claude pricing page](https://www.anthropic.com/pricing) now lists Opus 4.7 at $5 / $25 per million tokens, Sonnet 4.6 at $3 / $15, and Haiku 4.5 at $1 / $5. For full Claude Code documentation, see the [official Claude Code docs](https://code.claude.com/docs/en/overview).

**OpenAI** released [GPT-5.5](https://openai.com/index/introducing-gpt-5-5/) on April 24. Inside Codex, OpenAI explicitly says it produces better results with fewer tokens than GPT-5.4 (see [OpenAI pricing](https://openai.com/api/pricing/)). The [Codex changelog](https://developers.openai.com/codex/changelog) over the last month also added Unix socket transport for the app-server, sticky environments, remote plugin install, automatic reviewer agents that gate risky approvals, in-app browser hand-off for local dev servers, and `codex exec --json` reasoning-token output. For full Codex CLI documentation, see the [official Codex CLI docs](https://developers.openai.com/codex/cli).

**Google** shipped [Gemini](/blog/gemini-deep-research) 3 Pro and Antigravity on April 22. Relevant context, but it does not change the head-to-head between the two terminal agents.

## Round 1: raw coding ability

This is closer than the marketing suggests. On hard, multi-file refactors in real repos, both Opus 4.7 and GPT-5.5 produce working diffs most of the time. The differences:

- **Opus 4.7 plans more.** It writes longer scratch reasoning, asks more clarifying questions, and is more willing to push back on a bad plan. This is great for ambiguous specs and painful for "just fix this lint error."
- **GPT-5.5 in Codex acts more.** Token-efficient, faster to a first diff, less internal monologue surfaced. For tightly scoped tasks (write this function, fix this test, port this util) it is often quicker.

Net: if you measure SWE-bench-style numbers, they look similar. If you measure your own happiness on a Tuesday, the personalities diverge.

```bash
# Same task, two agents
claude -p "add a /healthz endpoint with 200 OK and a tiny test"
codex exec "add a /healthz endpoint with 200 OK and a tiny test"
```

For tasks at that altitude, Codex usually finishes first.

## Round 2: extensibility and customization

This is where Claude Code is currently in a different league.

The skills ecosystem became real this month. The community-curated [claudemarketplaces.com](https://claudemarketplaces.com/) directory crossed 150 skills in March and the open-source [claude-code-plugins-plus-skills](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) marketplace lists 423 plugins, 2,849 skills, and 177 agents. A skill is a Markdown file. For the current extension model, start with the [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins):

```
~/.claude/skills/deploy-vercel/SKILL.md
```

A plugin bundles skills, MCP servers, slash commands, and sub-agents into one installable unit. Hooks let you run shell commands at lifecycle events (see [hooks documentation](https://code.claude.com/docs/en/hooks)). Sub-agents let you fan work out cleanly. None of this requires SDK code.

Codex's plugin model exists - the recent changelog added remote plugin install and marketplace upgrades - but it is younger, smaller, and less culturally embedded. If you want a community library to copy from on day one, Claude Code wins.

If your team already has an `AGENTS.md` or [DESIGN.md](/design-system) and a folder of skills, that investment compounds in Claude Code. Move to Codex and most of it does not transfer.

## Round 3: defaults and reviewer behavior

Codex catches up here, and arguably surpasses Claude Code.

The new automatic reviewer agent in Codex CLI gates risky approvals through a separate agent before they execute. Permission profiles round-trip across TUI sessions, user turns, MCP sandbox state, and shell escalation. The in-app browser lets Codex click through a real local app to verify a fix. `codex exec --json` reports reasoning-token usage so you can budget cost programmatically.

Claude Code's hook system is more flexible (you can run any shell command on `PreToolUse`, `PostToolUse`, `Stop`), but Codex's defaults out of the box are tighter. If you want a junior teammate to run an agent and not break prod, Codex is the safer first install.

## Round 4: cost

Use this as a decision frame, not a price calculator:

- **Opus 4.7 only:** highest Claude API cost, but strongest when the task needs deep planning.
- **Opus 4.7 planner + Haiku 4.5 sub-agents:** often cheaper when the subtasks are narrow enough for a faster model.
- **GPT-5.5 in Codex:** check both [OpenAI API pricing](https://openai.com/api/pricing/) and [Codex pricing](https://developers.openai.com/codex/pricing), because the right answer depends on model choice, token use, and plan limits.
- **[Claude Max](https://www.anthropic.com/pricing) or [ChatGPT Pro](https://openai.com/chatgpt/pricing/):** flat-rate plans may be the right answer if you run an agent for hours every day, but plan limits and included usage can change.

For pricing tiers, see our [Q2 2026 AI coding tools pricing breakdown](/blog/ai-coding-tools-pricing-q2-2026).

## The verdict, by job

**Pick Claude Code when:**

- The task is ambiguous and benefits from planning ("redesign our auth flow," "split this monolith")
- You want to invest in skills, hooks, sub-agents, MCP servers as long-lived team infrastructure
- You already have an `AGENTS.md` / `CLAUDE.md` / [DESIGN.md](/design-system) and want the agent to actually read them
- You care about UI/visual taste (Opus 4.7's vision and design output is genuinely better)
- You want to run multi-agent fan-outs from one orchestrator

**Pick Codex when:**

- The task is well-scoped (fix this test, write this function, refactor this file)
- You want strong defaults and an opinionated approval/review loop without configuring much
- You need the in-app browser to click through a local UI
- Cost-per-task matters and you do not have a flat-rate plan
- The team is new to agent CLIs and you want fewer ways to shoot yourself in the foot

**Use both when:**

- You are running serious software and want second opinions. A pattern that works: Claude Code for planning and architectural diffs, Codex for tightly scoped follow-ups. They commit to the same branch, you read the PR.

## A practical setup

Here is the configuration most heavy users I trust are running this week.

`~/.claude/settings.json`:

```json
{
  "model": "claude-opus-4-7",
  "subagent_model": "claude-haiku-4-5"
}
```

`~/.codex/config.toml`:

```toml
model = "gpt-5.5"
auto_review = true
```

Then alias them so your fingers pick the right tool:

```bash
alias plan="claude"        # ambiguous, big-picture
alias do="codex"           # tight, well-scoped
```

It sounds silly. It works.

## What this means for the next quarter

Both products are converging on "agent that reads your repo, plans, edits, runs, verifies." They will keep getting closer on raw ability. The differentiation is going to be:

- **Claude Code:** the ecosystem (skills, plugins, marketplaces, MCP). Your team's accumulated context lives here.
- **Codex:** the loop (reviewer, browser, sandbox, sticky environments). The product around the model.

If I had to bet, the team that wins is the team whose users build things on top of it without permission. That favors Claude Code in the long run. But Codex's April 2026 release is the closest the gap has been, and on a strict cost-per-task basis it is currently the better default for "small, scoped" coding work.

For a deeper field comparison including Cursor and OpenCode, see our [four-way matchup](/blog/claude-code-vs-codex-vs-cursor-vs-opencode).

## Frequently Asked Questions

### Which is better for coding in 2026: Codex or Claude Code?

Neither is universally better - they optimize for different workflows. Claude Code excels at ambiguous, planning-heavy tasks where you want the agent to think deeply before acting. It has a mature skills and plugin ecosystem for team customization. Codex excels at well-scoped tasks where you want fast execution with strong defaults and built-in safety rails. For most developers, the answer is "use both" - Claude Code for architecture and planning, Codex for tight implementation work.

### How much does Codex cost compared to Claude Code?

Codex and Claude Code cost depend on model choice, token use, and whether you are using API pricing or a flat-rate subscription. Claude's current pricing page lists Opus 4.7 at $5 / $25 per million tokens, Sonnet 4.6 at $3 / $15, and Haiku 4.5 at $1 / $5. For Codex, check [OpenAI API pricing](https://openai.com/api/pricing/) and [Codex pricing](https://developers.openai.com/codex/pricing) before making a cost call.

### What models power Codex and Claude Code in April 2026?

Codex runs GPT-5.5 (released April 24, 2026), which OpenAI says produces better results with fewer tokens than GPT-5.4. Claude Code runs Claude Opus 4.7 (released April 16, 2026), roughly 13% better than Opus 4.6 on coding benchmarks with stronger vision capabilities. Both are significant upgrades from the models available even a few months ago.

### Can I use both Codex and Claude Code on the same project?

Yes, and many developers do exactly this. A common pattern: use Claude Code for planning and architectural decisions, then use Codex for tightly scoped follow-up tasks. Both agents can commit to the same branch, and you review the combined PR. This dual-agent approach gives you second opinions and plays to each tool's strengths.

### Which agent has better defaults out of the box?

Codex currently has tighter defaults. The automatic reviewer agent gates risky approvals, permission profiles persist across sessions, and the in-app browser lets it verify changes by clicking through your local dev server. Claude Code's hook system is more flexible - you can run any shell command at lifecycle events - but requires more setup. For teams new to agent CLIs, Codex is the safer first install.

### Which has the better plugin ecosystem?

Claude Code wins here decisively. The skills ecosystem crossed 150 community skills on claudemarketplaces.com, and the open-source claude-code-plugins-plus-skills marketplace lists 423 plugins, 2,849 skills, and 177 agents. Codex's plugin model exists and recently added remote install, but it is younger and smaller. If you want community resources to copy from on day one, choose Claude Code.

### What is the main philosophical difference between Codex and Claude Code?

Claude Code optimizes for extensibility on top of a planning model - skills, sub-agents, hooks, MCP servers, and plugins are first-class concepts. The bet is that you will customize the agent to your repo and team. Codex optimizes for a tightly integrated agent loop with strong defaults - the model, CLI, app-server, browser, and reviewer are designed to work well out of the box without much configuration.

### When should I use Claude Code instead of Codex?

Use Claude Code when: the task is ambiguous and benefits from planning (redesigning auth flow, splitting a monolith), you want to invest in skills and hooks as team infrastructure, you already have AGENTS.md or CLAUDE.md files you want the agent to respect, you care about UI and visual taste (Opus 4.7's vision output is better), or you want to run multi-agent fan-outs from one orchestrator.

### When should I use Codex instead of Claude Code?

Use Codex when: the task is well-scoped (fix this test, write this function), you want strong defaults without much configuration, you need the in-app browser to verify changes visually, cost-per-task matters and you lack a flat-rate plan, or your team is new to agent CLIs and you want fewer footguns.



Convex to Neon: The Playbook After 4 App Migrations
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

A week ago I wrote up the Convex to Neon migration on a single app, dd-clipper, as a practical notes post. Five tables, five PRs, a planning doc, and a list of lessons we paid for in time.

Tonight three more apps shipped the same migration in one sitting. dd-skills-marketplace, dd-hooks-directory, dd-mcp-directory. A fourth, adcraft-ai, is in flight. One app is an anecdote. Four apps is a pattern.

This post is the sequel. It pulls the moves that worked on dd-clipper out of the war story and writes them down as a reusable playbook. What stayed identical across every app. What was actually app-specific. And the part everyone wants the number for, how much faster the second migration was than the first.

## Why this post exists

The first migration is a project. You discover the shape as you go. You write a planning doc, you find out which guarantees you were quietly relying on, you get burned by a credit deduction race, you realize file storage is a separate problem.

For the implementation path around this, pair it with [How to Build Full-Stack TypeScript Apps With AI in 2026](/blog/build-apps-with-ai) and [The Next.js AI App Stack for 2026](/blog/nextjs-ai-app-stack-2026); those guides connect the idea to a shippable TypeScript stack.

The second migration is a checklist. You already know what `useQuery` reactivity replaces with. You already know `UPDATE ... RETURNING` is the credit pattern. You already know the deprecated `convex/` directory stays in the repo for a release. You already know what the README cutover note looks like.

The third and fourth are template work. Lift the schema layout, point an agent at the table list, run the playbook, ship. That is the speed-up. Not a clever trick, just the normal compounding you get when you stop solving the same problems twice.

For portfolio context, see the [DD apps overview](/apps) and the [stack comparison page](/compare). For the tooling story behind running four migrations in one night, the [overnight agents post](/blog/12-tools-in-one-night-with-claude-code) covers how the agent fan-out actually worked.

## The seven step playbook

Every one of the four migrations followed the same seven steps in the same order. This is the version that is now copy-pasted into a checklist file at the top of each migration PR.

1. Inventory. List every Convex table, every consumer of every table, every callsite of `useQuery`, `useMutation`, and `_storage`. This becomes the planning doc. Half a page is fine. The point is that nothing surprises you in step five.
2. Schema first. Write the Drizzle schema for every table before touching application code. Migrations file, types, exports, done. You should be able to `pnpm db:push` against a fresh Neon branch and see the empty tables come up.
3. Lazy proxy. Add a `db/` module per table with the same shape the old `convex/.ts` exported. Import lazily so the dev server does not crash on missing env vars in unrelated routes. This is the part most people skip, and it is the reason migrations stall in review.
4. Replace callsites table by table. One PR per table where you can. Inside each PR, the old `convex/.ts` does not get deleted, it gets a `// @deprecated` banner and an empty body that throws a clear error if anyone still imports it. Generated client types stay valid, downstream SDKs do not break.
5. Atomic writes audit. Every place the old code relied on Convex single-writer semantics gets rewritten as a single SQL statement. `UPDATE ... RETURNING`, `INSERT ... ON CONFLICT`, `SELECT ... FOR UPDATE` inside a transaction. No SELECT-then-UPDATE patterns survive review.
6. Reactivity decision. Before merging the first user-facing PR, write down what replaces `useQuery`. Polling interval, optimistic updates, server-sent events, or "we accept staleness." This is a one paragraph decision. Do not skip it and do not defer it.
7. README cutover note. Last commit on the migration branch updates the README with the new connection variable, the new migration command, and a note that `convex/` is deprecated and removed on the next release. Without this, the next person who clones the repo runs `npx convex dev` and is confused for an hour.

That is the whole playbook. Seven steps, no novelty, all boring on purpose.

## What was identical across all four apps

Four things were exactly the same in every migration. Word for word in some cases. These are the parts you can lift verbatim.

**The lazy proxy pattern.** Every `db/` module wraps Drizzle calls in a function that constructs the client on first call, not at import time. Without this, any route that imports a sibling module gets an "env var missing" crash in dev when you have not yet wired up `DATABASE_URL` for that route. The pattern is three lines and it shipped unchanged in dd-clipper, dd-skills-marketplace, dd-hooks-directory, and dd-mcp-directory.

**The deprecated `convex/` directory.** None of the four migrations deleted Convex on the way out. Each one kept the directory, marked every file with a deprecation banner, and stubbed the exports to throw a readable error. This protects the generated Convex client types that downstream tooling sometimes still references during a release window. Deletion happens in a follow-up PR after one full deploy cycle.

**The atomic `UPDATE ... RETURNING` for any counter.** Saves counts, install counts, ratings totals, credit balances. Every app had at least one of these. Every app got the same single-statement pattern. This is the lesson from dd-clipper that paid for itself three more times.

**The README cutover note.** Same three bullet points each time. Where the database URL goes, what the migration command is, and what is deprecated. It is the smallest part of the playbook and the highest hit rate on developer confusion when it is missing.

If you are running this migration on your own app, those four are the parts you do not have to think about. They are not load-bearing decisions, they are just the right answer.

## What differed per app

Three things were genuinely app-specific. This is where the playbook stopped being a copy-paste and started needing judgement.

**Table count and shape.** dd-clipper had five tables and a real domain model with credits, usage logs, and clips. The directory trio (skills, hooks, mcp) had four small tables each with the same shape, basically `items + saves + installs + ratings`. adcraft-ai has seven and a more complex one, including users, generations, canvas elements, and brand kits. The playbook scales to all three sizes, but the work per table is not constant. Domain tables with business logic take longer than directory join tables, and the second migration did not magically make domain logic faster.

**Reactivity tolerance.** The directory trio did not need `useQuery` reactivity at all. A user saves a hook, the page revalidates on next nav, nobody notices. dd-clipper needed reactivity for the clip library and we made the call to accept polling. adcraft-ai has a canvas with multiple elements being edited and that is genuinely a place where reactivity matters, so the migration there has to pick a real-time layer up front, not punt. The playbook step says "make the decision," not "the decision is the same." Across four apps the decision was different three times.

**File storage.** dd-clipper had clip blobs in Convex `_storage`. The directory trio had no file storage at all, which made their migrations meaningfully smaller. adcraft-ai has generated images and brand kit assets, which is its own project on top of the table migration. The playbook explicitly separates these. If your app has files, expect the migration to be two projects, not one. If it does not, you just got a free speed-up.

## The speed numbers, honestly

Here is the part everyone wants. I am going to be direct because the rounded version is misleading.

dd-clipper took most of a week of evenings. Five PRs, a planning doc, a real war story. Some of that was migration work. A lot of it was figuring out the playbook by hitting walls.

The directory trio shipped tonight in one sitting. Not parallelized in the agent-team sense, but each migration was under an hour of focused work once the playbook was in hand and an agent was running the table-by-table scaffolding. Three apps, one evening, three merged PRs. The PRs are small because the apps are small, and the apps are small because they are directories, but the structural reason it was fast is that none of the seven steps required new thinking.

The honest framing is this. The first app paid for the playbook. The second app validated it. The third and fourth apps were the payoff. If you are looking at a portfolio of similar apps and trying to decide whether to migrate the cheap one first or the expensive one first, do the expensive one first. The playbook you build will pay for itself across everything else.

adcraft-ai is in flight as I write this. Seven tables, real reactivity needs, file storage to plan around. I expect it to land somewhere between dd-clipper and the directory trio in time, probably closer to dd-clipper because the domain logic is real. The flagship site, developers-digest-site, has seventeen tables and is on deck after that. That one is its own multi-PR series.

## When this approach is right, and when it is not

The playbook is right when you have a portfolio of small to medium apps that all share Convex as a dependency, you already run Postgres elsewhere, and the split-stack tax across apps is real. The compounding only happens if you have more than one migration to do.

The playbook is right when your reactivity needs are tractable. Polling works for directories. Polling plus optimistic updates works for most CRUD. If your app genuinely needs collaborative editing or live presence, the migration is still doable, but the reactivity decision in step six is now a real architecture project, not a paragraph.

The playbook is wrong when your app is one app and it works fine on Convex. The first migration cost is real. You only get the speed-up if there is a second app to apply it to. If you have one Convex app and it ships, leave it.

The playbook is wrong when most of your data is files. If your Convex usage is mostly `_storage` with a thin metadata table on top, the migration is a file storage project with a side of SQL, and the seven steps above are the wrong frame.

If your app is on Convex, working, and you are trying to decide whether any of this applies to you, the [tools comparison page](/compare) has the side-by-side and the rest of the migration notes in this series cover the trade-offs in more detail.

Four apps in, the migration is no longer interesting. That is the goal. Boring is the point. The next app is just the playbook again.


The DD Stack Cookbook: Five Recipes That Compose
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

The DD product line stopped being a pile of standalone tools a few weeks ago. Once agentfs landed, the rest of the stack started snapping into it like puzzle pieces. This post walks through five recipes that show how the products compose. Each one is something you can actually wire up today, not a pitch deck diagram.

The pattern across all five: small, sharp tools that speak the same protocols (MCP, hooks, plain JSON on disk), so chaining them together does not require glue code.

## Recipe 1: Give your agent a real persistent filesystem

**Stack:** agentfs + agentfs-mcp + [Claude Code](/blog/what-is-claude-code-complete-guide-2026)

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

The default model of agent state is a pile of context window plus whatever the harness happens to remember between sessions. That falls apart the moment your agent runs longer than a single conversation, or you want two agents to share work, or you need to come back tomorrow and pick up where you left off.

agentfs is a content-addressed filesystem with branch and snapshot semantics. agentfs-mcp exposes it over MCP so any compatible agent can read and write. Claude Code is the harness.

Wire it up:

```bash
agentfs init my-agent-workspace
agentfs-mcp serve --workspace my-agent-workspace --port 7331
```

Add to `.claude/mcp.json`:

```json
{
  "mcpServers": {
    "agentfs": {
      "command": "agentfs-mcp",
      "args": ["client", "--port", "7331"]
    }
  }
}
```

Now when Claude Code writes a file, it writes through agentfs. The agent gets `read`, `write`, `list`, `branch`, and `snapshot` tools. The state survives restarts, can be diffed, and can be branched off for parallel exploration. The agent does not have to know any of that. It just sees a filesystem.

The payoff: long-running agent runs that span days. Crash recovery without losing work. The ability to point a fresh agent at a workspace and have it pick up the thread.

A note on performance. agentfs is content-addressed, so writing the same file twice [costs](/blog/ai-coding-tools-pricing-comparison) almost nothing. Branching is metadata-only. We have run workspaces with 50k files and tens of thousands of snapshots without measurable slowdown on read or write. The cost model is roughly that of a local git repo, with the snapshot operation being closer to free.

## Recipe 2: Auto-snapshot every Write tool call

**Stack:** Hookyard agentfs-checkpoint hook + agentfs

Snapshots are only useful if you actually take them. Asking the agent to remember to snapshot is the same mistake as asking humans to remember to git commit. The fix is automation at the harness layer.

Hookyard ships an `agentfs-checkpoint` hook. It runs on every `PostToolUse` event for `Write`, `Edit`, and `MultiEdit`, and writes a snapshot to the active agentfs branch with the tool call as the message.

Drop it in:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          { "type": "command", "command": "hookyard run agentfs-checkpoint" }
        ]
      }
    ]
  }
}
```

Every file edit becomes a checkpoint. If the agent goes off the rails three hours into a run, you can `agentfs log`, find the checkpoint right before the bad turn, and `agentfs reset` to it. No more blowing away an entire session because of one wrong edit.

There is one knob worth tuning: snapshot rate on a busy run can produce hundreds of checkpoints. Set `HOOKYARD_AGENTFS_DEBOUNCE=30s` if you want coarser granularity.

## Recipe 3: A curated, gated skill library for your team

**Stack:** Skills marketplace + dd-pr skill

The skills marketplace launched this week. The dd-pr skill landed alongside it. Together they solve a problem most teams hit by month two of running [coding agents](/blog/what-is-an-ai-coding-agent-2026): skills proliferate, half are wrong, and there is no review gate before a skill ships to everyone's harness.

Here is the workflow:

1. A team member writes a new skill locally in their `~/.claude/skills/` directory.
2. They run the dd-pr skill: `claude /dd-pr "publish skill my-skill"`. It branches, pushes, and opens a private PR against the team's skills repo.
3. Review happens in GitHub. Devin or a human reviews the SKILL.md, the scripts, and the tool surface.
4. On merge, the marketplace indexer picks it up. Team members `claude-skills sync` and pull the new skill.

The marketplace handles discovery and versioning. dd-pr handles the gate. Neither tool is interesting on its own. Together they turn an ungoverned mess into a curated library where every skill in production has been read by at least one other person.

The marketplace also supports private orgs, so you can ship internal skills (database migrations, deploy runbooks, ticket triage) without making them public.

One more thing the dd-pr skill does that matters here: it tags the review automatically. Our convention is to tag @devin-ai-integration on every skill PR for a first-pass read. Devin catches the obvious problems (missing frontmatter, broken script paths, accidentally checked-in secrets) before a human reviewer ever sees the PR. By the time a teammate opens the diff, it is usually mergeable.

## Recipe 4: Agent-readable eval suites

**Stack:** agent-eval-bench + agentfs

Evals are the part of agent development that everyone knows they should do and most people skip. The friction is not the eval logic. It is the storage. You end up with a folder of JSON files on someone's laptop and no way for the agent itself to read its own scoreboard.

agent-eval-bench writes eval suites and results as JSON. agentfs is a filesystem that agents can natively read. Point one at the other.

```bash
agent-eval-bench run \
  --suite suites/coding.yaml \
  --output agentfs://eval-results/$(date +%Y-%m-%d)/coding.json
```

Every run lands in agentfs at a predictable path. Now the agent can read its own eval history:

```
> read eval-results/2026-04-27/coding.json
{
  "suite": "coding",
  "score": 0.84,
  "regressions": ["test_async_iter", "test_unicode_path"],
  ...
}
```

This unlocks a whole class of self-improvement loops. The agent can compare last week's run to this week's, find regressions, and propose fixes. Or you can run a meta-agent that watches for score drops and opens a private PR with a hypothesis.

The shared substrate is the trick. Both tools speak JSON to the same filesystem, so no integration work was needed.

## Recipe 5: Host the agentfs MCP server inside agentfs

**Stack:** mcpaas + agentfs-mcp

This one is a little recursive but it is genuinely useful in production.

mcpaas is a hosted runtime for MCP servers. You give it a server binary and a config, it gives you a URL. agentfs-mcp is the MCP server that exposes agentfs.

You can run agentfs-mcp inside an agentfs workspace, hosted by mcpaas. The server's own code, logs, and runtime state live in the same filesystem it is exposing. The setup looks like this:

```bash
agentfs init mcpaas-runtime
agentfs cp $(which agentfs-mcp) mcpaas-runtime:/bin/agentfs-mcp

mcpaas deploy \
  --workspace mcpaas-runtime \
  --binary /bin/agentfs-mcp \
  --args "serve --workspace ."
```

Three things this gets you. First, the MCP server's own state is snapshotted by the same hook chain you use for everything else. If a bad deploy corrupts the server, you roll back with `agentfs reset`. Second, the server can read its own source code and config, which makes self-updating servers tractable. Third, you can branch the entire runtime to test a config change, point an agent at the branch, validate, then merge.

It sounds cute until you have run a production MCP server for a month. Then it sounds like the only sane way to do it.

## What composes these

A short list of the design choices that made these recipes possible.

**One protocol per surface.** MCP for tool calls, hooks for lifecycle events, plain JSON files for shared state. No bespoke RPC.

**Files as the universal interchange.** agentfs is the substrate. Every tool that produces structured output writes JSON to a path. Every tool that consumes structured input reads JSON from a path. The agent does not need adapters.

**Private by default.** Skills, repos, deploys all default to private. You opt in to public, never the other way around.

**Hooks are first class.** Hookyard treats hooks like packages. You install them, version them, and chain them. This is how Recipe 2 stays a one-liner.

## What to build next

The cookbook is going to keep growing. A few combinations on the short list that are not shipped yet:

- agent-eval-bench results streamed back into Claude Code as context, so the agent can see its own track record before making a decision.
- Hookyard hook that runs an eval suite on every commit and blocks merges on score regressions.
- mcpaas multi-tenant mode where each agentfs workspace is its own tenant with isolated MCP servers.

If you want to build any of these, the repos are all up. Small, sharp tools. Compose them.

The full DD stack is at [developersdigest.com](https://developersdigest.com). Each product has its own docs and a private repo for issues. Email if you want access.


DESIGN.md: The Contract That Keeps AI Agents On Brand
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Drift Problem

Hand a [coding agent](/blog/what-is-an-ai-coding-agent-2026) a vague prompt and you can predict what comes back. Rounded corners that drift larger every iteration. A pastel palette nobody asked for. A hero with three CTAs stacked vertically. Soft shadows under every card. Decorative icons next to every list item. Marketing copy that uses the word "seamless" twice in one paragraph.

Agents trained on the public web have absorbed an aesthetic. Call it the default look. It is not ugly. It is just generic, and once you notice it you cannot unsee it. Every generated UI starts to feel like a sibling of every other generated UI, which is a problem if you are trying to build something that has a point of view.

The drift is not a model failure. It is a context failure. The agent is making reasonable inferences from the prompt and from whatever fragments of your codebase it happened to read first. If your repo does not state the rules out loud, the rules get invented on the fly, and what gets invented is whatever the model has seen most often.

The fix is boring and obvious. Write the rules down. Put them somewhere the agent will read before it writes a single component. That document is DESIGN.md.

## DESIGN.md As The Contract

A DESIGN.md at the root of your repo is not documentation. Documentation is a thing humans skim once and forget. DESIGN.md is a contract the agent has to honor every time it produces UI. The framing matters because it changes how you write the file. You are not explaining the system to a new hire who will absorb taste over six months. You are giving an agent a checklist that determines whether the output is acceptable.

The contract has to be specific enough that compliance is testable. Vague principles like "feel modern but human" are useless. Concrete rules like "buttons are always pill shaped, 8px by 24px padding, primary buttons are black with white text" are enforceable. If the agent ships a square button with a soft shadow, you can point at the line in the file and the conversation is over.

The other reason to treat it as a contract is that contracts get versioned. When you change a token, the file changes. When you ban a pattern, the file changes. The agent reads the current version every session, so the rules stay live instead of going stale in a Notion page nobody opens.

## What Goes In It

There are six sections that pay for themselves. Skip any of them and the agent will fill the gap with whatever feels reasonable, which is usually wrong.

Palette. Every color the system uses, with hex codes and a one-line job description for each. Not a mood board. A list. Background, surface, foreground, muted text, accent, error. State the rules around adjacency. If accent on background has poor contrast, say so explicitly so the agent does not pair them.

Type scale. Font family, weights you actually use, the specific sizes and line heights for display, headings, body, and labels. Letter spacing rules. Whether negative tracking is allowed. The agent needs numbers, not adjectives.

Spacing and shape. The base grid unit. The radii you allow and what each one is for. The container width and gutter. Whether shadows are permitted. If you use an offset card pattern instead of shadows, describe it precisely enough that the agent can produce it from the description alone.

Component patterns. Buttons, cards, inputs, navigation, badges, code blocks, media frames. For each one, the exact treatment. Utility class names if you have them. The agent should be able to read the file and pick the right class without guessing.

Voice rules. Banned words and phrases. Tone constraints. Whether emojis appear in copy. Whether marketing superlatives are allowed. Voice drifts faster than visuals because the agent has stronger priors about how SaaS landing pages sound.

Banned tokens. The shortest section and the most important one. A flat list of things that are not allowed in this system. Gradients. Box shadows. Glass morphism. Pink text on cream backgrounds. Em dashes. Square buttons. Generic dashboard mockups. Naming the bad patterns kills them faster than describing the good ones.

## A Real Example

The Developers Digest repo runs on a Gumroad inspired system. Cream pages, white surfaces, black type, black borders, pink accents, pill buttons, offset layer cards. The [live design-system page](/design-system) shows the shipped tokens and components, while the DESIGN.md at the root states all of this in roughly two hundred lines. The frontmatter declares the tokens as YAML so they can be parsed. The body explains the intent and the rules.

Three lines from the do-not list illustrate why the file works. Do not use gradients. Do not use box shadows. Do not use pink text on cream backgrounds for important copy. Each one is a specific failure mode the agent would hit otherwise. Each one is short enough that there is no ambiguity.

The components section names the utility classes the codebase actually ships. btn-pill-primary. gumroad-card. bg-offset-layer. When the agent generates a new card, it reaches for the existing class instead of inventing a new one with slightly different padding. That single behavior is worth more than any amount of prose about consistency.

There is a companion file called DESIGN-DIRECTION.md that captures the strategic layer. Where the system is heading. What to borrow from reference sites. What to avoid. The split matters because the contract layer needs to be stable and the strategy layer needs to evolve. Mixing them produces a file that is too long for the agent to honor and too volatile for humans to trust.

## How Claude Code Reads It

[Claude Code](/blog/what-is-claude-code-complete-guide-2026) looks for context files at the root of the repo by default. CLAUDE.md is the primary entry point. DESIGN.md sits alongside it and gets pulled into context when the work involves UI. The agent does not need to be told to read it. If the file is there and the task is about a component or a page, it shows up.

The practical move is to reference DESIGN.md from CLAUDE.md explicitly. One line that says: for any UI work, follow the rules in DESIGN.md. That removes the ambiguity. The agent treats the design file as load bearing instead of optional reading.

For repos that use [Codex](/blog/openai-codex-guide) or other agentic tools, the same pattern works with a different filename. Whatever entry point the tool reads, point it at DESIGN.md. The file itself stays the same. The wiring around it adapts to the tool.

The other thing that helps is a short section near the top of DESIGN.md that lists banned tokens with no explanation. The agent scans the file and the banned list anchors immediately. If you bury the prohibitions inside paragraphs of prose, they get summarized and softened. A flat list cannot be softened.

## Three Traps To Avoid

Overengineering is the first trap. The temptation is to write a hundred page design system spec with every edge case enumerated. The agent will not read all of it. The humans on your team will not read any of it. Aim for the shortest file that prevents the failures you actually see. If the agent never produces gradients, you do not need to ban them. If the agent ships a gradient every other session, the ban goes at the top.

Treating the file as documentation is the second trap. Documentation describes the system. A contract constrains it. The difference shows up in the verbs. Documentation says "the system uses pill buttons." A contract says "buttons are always pill shaped. Square buttons are not allowed." The second version is enforceable and the first one is decorative.

Drifting from the file is the third trap and the most common one. You write the rules. You build a few components that follow them. Then you ship a one off page that breaks three rules because the deadline was tight. The agent reads the codebase, sees the exception, and starts producing more exceptions. The contract decays from inside the repo. The fix is to either update the file when you make a real exception or refuse the exception. There is no third option that scales.

A related failure is letting the file fall behind the code. If you migrate from one accent color to another and the file still lists the old hex, the agent will use the old hex. Treat DESIGN.md the same way you treat a schema. When the system changes, the file changes in the same commit.

## Wiring It Into Practice

The smallest version of this is one file at the root of the repo, two hundred lines, written as a contract. The next version adds a reference from CLAUDE.md so the agent knows to honor it. The version after that adds a banned tokens section and a brand voice section that ban the words you do not want shipped.

Across the DD app portfolio the same pattern shows up everywhere. Each app has its own DESIGN.md tuned to its surface. The shared rules sit in a brand voice doc that every repo points at. New posts and pages get cross referenced through the [comparison page](/compare) and the [apps directory](/apps) so the agent has working examples to look at when it generates new content. The [ten tools post](/blog/ten-tools-for-agent-infrastructure) and the [meta post on agentic dev workflow](/blog/agentic-dev-stack-2026) show the same approach applied to different surfaces.

The thing to internalize is that agents are not going to develop taste. They are going to follow the rules they are given. If you do not write the rules down, the rules get borrowed from the average of the public web, and the average of the public web is the generic look you are trying to escape. DESIGN.md is the cheapest possible escape hatch. One file. Two hundred lines. The output stops drifting.

The work is not in the writing. The work is in the willingness to be specific. State the palette. State the type scale. State the components. State the bans. Commit it to the root. Reference it from the agent entry point. Update it when the system changes. That is the entire system, and once it is in place the conversation about whether the generated UI is on brand stops being a conversation at all.


Introducing agentfs: A Filesystem for AI Agents
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Storage Problem for Agents

Agents need to read and write files. That sounds boring until you try to actually do it in production.

Most [agent frameworks](/blog/ai-agent-frameworks-compared) paper over the problem with one of three options. The first is the local disk on whatever VM the runtime happens to be sitting on. That works for a single process, but the next agent run starts on a different machine and cannot find anything. The second is a blob store like S3. That works at scale, but it is shaped wrong. Listing a prefix is not the same as listing a directory. Atomic rename is fiddly. Reading a slice of a file means signed URLs and range headers. Most agent code is written as if there is a real filesystem underneath, and there is not. The third is a sandbox like E2B or Daytona. That gives you a real disk, but the disk dies when the sandbox dies, and the cold start cost is real.

None of these is wrong. They are answers to different questions. The question we kept hitting is smaller and more specific. Where does an agent put a file when it wants to come back to it tomorrow, from a different process, on a different machine, without spinning up a VM to find it?

That is the question agentfs is built to answer.

## What agentfs Is

agentfs is a virtualized filesystem for AI agents, backed by [Neon](/tools/neon) Postgres. You talk to it over HTTP. Files have paths. Directories list. Reads and writes are atomic at the file level. There is no machine to provision and no container to wait on.

The model is intentionally small. A workspace is a tree. A path is a string. A file is a blob with metadata, a content type, and a version. Operations are the ones you would expect: `read`, `write`, `list`, `move`, `delete`, `stat`. There is no shell. There is no `exec`. There is no way to ask the filesystem to run code on your behalf, because the filesystem is not a sandbox and pretending otherwise is how you get the four hundred dollar overnight bill we wrote about in [Agent FinOps](/blog/400-dollar-overnight-bill-agent-finops).

Under the hood, every workspace lives in a Neon branch. Metadata is a few Postgres tables. File contents up to a small size sit inline in Postgres. Larger blobs will spill to object storage in a later release, transparently. Because Neon scales to zero and resumes in milliseconds, there is no cold start to speak of from the agent's point of view. You hit the API, you get the bytes back, you move on.

The pitch is simple. Filesystem-shaped storage for agents. Pay-only. Postgres-backed. No cold starts. No exec, by design.

## What agentfs Is Not

It is worth being explicit about what is out of scope, because being honest about scope is how products earn trust.

agentfs is not a [code execution sandbox](/courses/sandboxes). If you need to run untrusted Python or compile a binary, reach for [E2B](/tools/e2b), [Daytona](/tools/daytona), or [Replit](/tools/replit). agentfs is the place those sandboxes can mount a workspace from, not a replacement for them.

agentfs is not a general object store. If your workload is hundreds of gigabytes of training data, S3 is fine and cheap. agentfs is shaped around files an agent reads and writes during a run: notes, drafts, intermediate state, generated code, partial outputs.

agentfs is not a database. There are no queries beyond path operations. If you want to search inside files, build the index in your application.

The point of saying no to these is to say yes, with confidence, to the workload that is left. That workload is large and underserved.

## The Pricing Thesis

There is no free plan.

That decision was deliberate, and it is worth explaining. Free plans on infrastructure products attract two kinds of users. The first kind never converts and never will. The second kind hits the free limit, churns to a competitor with a higher free limit, and treats the product as a commodity. Neither group helps the people who actually need the product to exist in two years.

The pricing is twenty dollars per month for the Plus plan, paid through Clerk Billing, with usage-based tiers above that for storage and request volume. Authentication is [Clerk](/tools/clerk). Billing is Clerk Billing. There is one button to upgrade and one place to manage everything.

Twenty dollars buys a working filesystem with enough headroom for a real agent project. If your agent is doing enough work that it needs more, the usage tiers handle that without a sales call. If you are not sure whether you need it, you probably do not, and that is a fine answer.

This is the same logic that drives the [Pay-Only Playbook](/blog/claude-code-usage-limits-playbook-2026): users who pay tell you the truth about what they need, users who do not pay tell you what they want for free. Both are useful, but only the first kind builds a durable business.

## API Tour

Here is the shape of the API. The full reference will land with v0.1.

### curl

```bash
# Write a file
curl -X PUT https://api.agentfs.dev/v1/fs/notes/draft.md \
  -H "Authorization: Bearer $AGENTFS_TOKEN" \
  -H "Content-Type: text/markdown" \
  --data-binary @draft.md

# Read it back
curl https://api.agentfs.dev/v1/fs/notes/draft.md \
  -H "Authorization: Bearer $AGENTFS_TOKEN"

# List a directory
curl https://api.agentfs.dev/v1/ls/notes \
  -H "Authorization: Bearer $AGENTFS_TOKEN"
```

### JavaScript

```js
import { AgentFS } from "@agentfs/sdk";

const fs = new AgentFS({ token: process.env.AGENTFS_TOKEN });

await fs.write("notes/draft.md", "# Draft\n\nFirst pass.");
const text = await fs.read("notes/draft.md");
const entries = await fs.list("notes");
```

### Python

```python
from agentfs import AgentFS

fs = AgentFS(token=os.environ["AGENTFS_TOKEN"])

fs.write("notes/draft.md", "# Draft\n\nFirst pass.")
text = fs.read("notes/draft.md")
entries = fs.list("notes")
```

The API is small on purpose. If your agent already speaks the Python `pathlib` or Node `fs/promises` shape, the wrappers should feel familiar within a few minutes.

## The Wedge: agentfs vs E2B, Daytona, Replit

The closest products in spirit are the agent sandboxes: [E2B](/tools/e2b), Daytona, [Replit](/tools/replit) Agent. They all have filesystems. So why a separate product?

Because their filesystem is a side effect of running a VM. The VM is the product. The disk goes away when the VM does. If you want a file to outlive the run, you write it somewhere else and read it back next time. That is a fine model when you also need to execute code, and a heavy one when you do not.

agentfs is the opposite trade. There is no VM. There is no execution. There is only the disk. If your agent runs in a sandbox today, it can keep running there and use agentfs as the place its files live across runs. If your agent does not need a sandbox at all, you skip the VM entirely and just talk to the API.

The simplest way to think about it: sandboxes are compute with a disk attached. agentfs is a disk with no compute attached. Most agent workloads need both, but they need them on different lifecycles. The disk should outlive the compute. Today they are coupled. agentfs decouples them.

Compare more options on the [tools comparison page](/compare) or browse the rest of the [Developers Digest apps](/apps).

## Roadmap Honesty

It is easier to get a product taken seriously when you are clear about what is in the box today and what is not.

v0.1 is the first public release. Files smaller than one megabyte. No code execution of any kind. No large binary blob support. No streaming reads or writes. No realtime change feed. No multi-region. Single workspace per account.

That is a deliberately small starting surface. Most agent files are small. Most agent files are text. The first version is sized to that case and nothing else. Trying to do more on day one is how products end up half-finished in three places.

What comes after v0.1, in rough order:

- Large file support, with object storage spill for blobs over the inline threshold.
- Streaming reads and writes, for agents that produce output token by token.
- A change feed, so a watcher process can react to new files without polling.
- Multiple workspaces per account, with separate access tokens.
- Snapshots and time travel, taking advantage of Neon branching.
- A small filesystem mount, for agents that genuinely cannot speak HTTP.

None of those ship in v0.1. Some may not ship at all. The roadmap is what we are working toward, not a promise. If you build on v0.1, you should build on what is there today, not what might be there later. We wrote more about how we think about this in the [build-in-public meta post](/blog/building-saas-with-ai-agents-2026).

## How to Try It

The repo is private while we scaffold. Sign up at agentfs.dev to get on the early access list. Authentication is Clerk, payment is Clerk Billing, the Plus plan is twenty dollars a month, and there is no free plan. If you want to read more about how we are thinking about agents and storage, the [agent memory patterns post](/blog/ai-agent-memory-patterns) covers the broader picture, and the rest of the [Developers Digest apps](/apps) shows what we are shipping alongside this.

agentfs is small on purpose. It does one thing. We think that thing is worth twenty dollars a month if you are building agents that need to remember anything across runs. If it is not, the cost of finding out is one month.


MCP Lens: Wireshark for Model Context Protocol Servers
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The visibility problem nobody talks about

[Model Context Protocol](/blog/what-is-mcp) is the connector format the entire agent ecosystem rallied behind. Claude Code uses it. Cursor uses it. Zed uses it. Most of the interesting integrations shipping in 2026 are MCP servers, not native plugins.

The transport everyone reaches for first is stdio. Spawn a subprocess, write newline-delimited JSON-RPC to its stdin, read responses from its stdout. Simple, portable, no port allocation, no auth dance. It is also completely opaque.

When something goes wrong in an MCP integration, your symptoms look like this. The host says the tool was called. The server logs nothing useful. The result is empty, or wrong, or the call hangs until the host times out. There is no devtools panel. There is no Network tab. The conversation between host and server is happening on file descriptors you cannot tap into without code changes on both sides.

I hit this wall four times in one week. A filesystem server returning paths that did not match what Claude thought it asked for. A custom search server quietly dropping the `cursor` argument because of a schema typo. A community server advertising a `resources/list` capability it never actually implemented. Every one of those bugs took an hour of squinting at logs to triage. None of them should have.

So I built a proxy.

## Meet MCP Lens

[MCP Lens](/) sits between any MCP host and any stdio MCP server. The host thinks it is talking to the server. The server thinks it is talking to the host. In the middle, every JSON-RPC frame in both directions is timestamped, parsed, and appended to a JSONL log. Optionally, a tiny local web UI tails that log over server-sent events and renders the conversation as a two-pane timeline.

The pitch I keep coming back to is the obvious one. This is Wireshark for MCP. You cannot debug what you cannot see. MCP Lens makes the wire visible.

It does one thing. It captures stdio. That is the whole feature surface today, and the constraint is doing real work for the design.

## Install and first capture

The repo is private for now. Clone it, install, build.

```bash
pnpm install
pnpm build
```

The binary lives at `dist/bin/mcp-lens.js` and is exposed as `mcp-lens` if you `npm link` it. To wrap any [MCP server](/blog/complete-guide-mcp-servers), prepend the `mcp-lens -- ` prefix to the command you would normally run:

```bash
mcp-lens --ui -- npx -y @modelcontextprotocol/server-filesystem /tmp
```

The double dash is load-bearing. Anything before it is a flag for MCP Lens. Anything after it is the real server command, spawned as a child process. MCP Lens pipes stdin and stdout bidirectionally, so the host above the proxy sees exactly the bytes the server emits, with no behavioural change.

Captures land in `./captures/session-.jsonl`. Override with `--out my-session.jsonl` if you want a stable path. The format is one frame per line:

```json
{
  "ts": 1714329000123,
  "dir": "client->server",
  "raw": "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\"}",
  "msg": { "jsonrpc": "2.0", "id": 1, "method": "initialize" }
}
```

`raw` is the exact bytes off the wire, `msg` is the parsed payload, `dir` tells you which side spoke. If a line is not valid JSON, `msg` is `null` and `parseError` carries the failure reason. That single detail has already paid for itself once: a server that was emitting a debug `console.log` to stdout corrupted its own JSON-RPC stream, and the parse error pointed at the offending line in seconds.

To wire it into [Claude Code](/blog/what-is-claude-code-complete-guide-2026), edit your MCP config and replace the existing entry:

```json
{
  "command": "mcp-lens",
  "args": ["--ui", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
}
```

Restart the host. Everything still works. You now have a recording.

## The inspector at localhost:4040

With `--ui`, MCP Lens boots a local server at `http://localhost:4040`. The page is intentionally boring. A frame list on the left, filterable by direction and free-text search. A detail pane on the right showing the full JSON-RPC payload with syntax highlighting. New frames stream in over SSE as the session continues, so you can watch a tool call happen as the host issues it.

The two filters that matter are `dir:client->server` and `method:tools/call`. Combine them and you have the exact list of every tool the host invoked, in order, with arguments. Click any frame and you see the matching response by id. That is roughly 80 percent of MCP debugging right there.

## Three real debugging stories

Three sessions from the last few days, all of them resolved in under five minutes once the wire was visible.

**Wrong tool arguments.** A custom GitHub search server kept returning empty arrays from inside Claude Code, but worked fine when I tested it manually. With MCP Lens running, I scrolled the timeline to the `tools/call` frame and saw the host had passed `{"q": "..."}` while the server's schema required `{"query": "..."}`. The host was silently coercing my prompt into the wrong argument name because the tool description had drifted from the schema. Fixed the description, restarted, gone.

**Missing capability.** A community-maintained MCP server advertised `resources/list` in its `initialize` response, then returned `Method not found` whenever the host actually called it. Without the proxy, this looked like the host being broken. With the proxy, the timeline made the contradiction obvious. The server's capabilities object was a copy-paste from a template, and the handler was never implemented. Filed an upstream issue with the JSONL attached.

**Schema drift.** This is the bug MCP Lens was born for. A self-hosted server changed its `tools/call` response shape from `{ content: [...] }` to `{ result: { content: [...] } }` between versions. The host kept showing empty tool results. Diffing two captures, one from the old version and one from the new, the structural change jumped out instantly. Until MCP Lens has built-in schema diff, `jq` is enough: `jq -c 'select(.msg.method=="tools/call")' old.jsonl new.jsonl` and your eye does the rest.

## What is not built yet

I am being deliberate about scope. MCP Lens does not, today, do any of the following.

Replay against a rebuilt server is not implemented. The capture format is replay-friendly by design, every frame has direction, raw bytes, and timestamp, but the harness to feed a captured client stream into a fresh server process is still a roadmap item. When it lands you will be able to rerun a bug-triggering session against a patched server without touching the host.

SSE and streamable-HTTP transports are not supported. Stdio only. Most MCP servers in the wild are still stdio, and tackling all three transports at once would have shipped nothing. The architecture is transport-pluggable, so HTTP transports are tractable, just not done.

Schema diff between two server versions, share-link export of a capture, and a tool-call timeline view with latency bars are all on the list. None exist yet. If you want any of them tomorrow, JSONL plus `jq` plus a few lines of Node will get you most of the way.

## Where it fits in the stack

MCP Lens slots in next to a few other small tools I have been writing about this month. [Promptlock](/blog/prompt-versioning-with-promptlock) makes the prompts you send to a model deterministic and reviewable. [TraceTrail](/blog/agent-replays-with-tracetrail) records full agent runs so you can rerun a session offline. [Hookyard](/blog/claude-code-hooks-with-hookyard) wires Claude Code hooks into pre and post events around your edits. MCP Lens covers the slice none of those touch: the bytes flowing between the host and the tools it actually uses.

If you are picking a stack for serious agent work in 2026, the [comparison matrix](/compare) is the right starting point. MCP Lens is not a model, not a framework, not a host. It is a debugger for the layer everyone forgot to build a debugger for.

## Try it

Clone, build, wrap one MCP server, open localhost:4040, and watch your host talk. The first time you see a tool call you assumed was working actually fail in the timeline, you will understand why this thing exists.


Promptlock: Deterministic Prompt Versioning for LLM Apps
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The bug you cannot see

Your eval scores dropped four points overnight. Nothing in `git log` looks suspicious. The model is the same. Temperature is the same. The retrieval pipeline did not change. Two hours into the investigation you discover that someone tightened the system prompt last Tuesday, replacing "Answer in a friendly tone" with "Answer concisely." The new wording is shorter. It is also worse.

This is prompt drift, and it is the most common silent regression in production LLM apps. Prompts are production code that nobody versions like code. They live in raw markdown files, untyped string constants, and the occasional Notion doc. There is no commit hash you can attach to a response. No diff you can show in code review. No way to say "this output came from prompt 7f3c1a9b8d22" and have anyone know what that means.

Promptlock is a small tool that fixes step one of that pipeline. Think of it as git for prompts, but actually deterministic. Every prompt template gets a stable 12-character id derived from a hash of the template, the variable schema, the model, and the temperature. You commit the resulting artifacts. You diff them. When something regresses, you have something concrete to point at.

## What Promptlock actually does

The core idea is content addressing. Given a tuple of `(template, variable schema, model, temperature)`, Promptlock computes a sha256 and truncates it to 12 chars. Same inputs always produce the same id. Different inputs always produce a different id. There is no central registry, no cloud service, and no API key. Versions live as JSON files under `.promptlock/` in your repo, next to the code that uses them.

The hash is intentional about what it covers. Variable values do not affect the id, only the variable schema does. That means swapping `language: "english"` for `language: "spanish"` keeps the id stable, but adding a new variable changes it. The model and temperature are part of the identity because the same template at temperature 0.2 is, in practice, a different prompt than the same template at temperature 0.8.

## Install and first run

```bash
npm install @developersdigest/promptlock
# or run the CLI directly
npx @developersdigest/promptlock --help
```

Register a prompt template:

```bash
echo "You are a helpful assistant. Answer in {{language}}." > prompt.md

promptlock add prompt.md \
  --model claude-opus-4-7 \
  --temperature 0.2 \
  --vars '{"language":"english"}' \
  --note "v1 baseline"
# -> 7f3c1a9b8d22  claude-opus-4-7  temp=0.2  v1 baseline
```

A new file appears at `.promptlock/7f3c1a9b8d22.json`. That is the artifact. It contains the template, the variable schema, the model, the temperature, the note, and a timestamp. Commit it.

Now edit the prompt and register again:

```bash
echo "You are a concise assistant. Answer in {{language}}." > prompt.md

promptlock add prompt.md \
  --model claude-opus-4-7 \
  --temperature 0.2 \
  --vars '{"language":"english"}' \
  --note "concise"
```

You get a new id. Both versions are now in `.promptlock/`. List them:

```bash
promptlock list
# 7f3c1a9b8d22  claude-opus-4-7  temp=0.2  v1 baseline
# a18b2c4e9011  claude-opus-4-7  temp=0.2  concise
```

And diff them:

```bash
promptlock diff 7f3c1a9b8d22 a18b2c4e9011
```

The output is a unified diff over the template plus the metadata. If a code review surfaced the second version, the diff is what a teammate would actually read. No "what changed in the prompt" guessing.

If you only want the id without writing anything, use `promptlock id prompt.md --model claude-opus-4-7 --temperature 0.2 --vars '{"language":"english"}'`. This is useful in CI checks that want to verify a deployed prompt matches a known good version.

## The SDK: wrap your LLM calls

The CLI is fine for ad hoc work, but the real value lands when you wire Promptlock into the code that calls your model. Here is a minimal example wrapping a [Claude API](/blog/tool-use-claude-api-production-patterns) call:

```ts
import Anthropic from "@anthropic-ai/sdk";
import { register } from "@developersdigest/promptlock";

const client = new Anthropic();

const template = "You are a helpful assistant. Answer in {{language}}.";
const vars = { language: "english" };
const model = "claude-opus-4-7";
const temperature = 0.2;

const version = await register({ template, vars, model, temperature });

const rendered = template.replace("{{language}}", vars.language);

const res = await client.messages.create({
  model,
  max_tokens: 1024,
  temperature,
  messages: [{ role: "user", content: rendered }],
});

logToObservability({
  promptId: version.id,
  response: res.content,
  latencyMs: res.usage,
});
```

The important line is `version.id`. Once that id flows into your logs, every response in your observability stack is tied to a specific, diff-able prompt artifact. When the eval score drops next Tuesday, you filter by id, see which prompt version produced the bad outputs, and run `promptlock diff` against the previous good version. The investigation goes from two hours to two minutes.

If you only need the id and do not want to write a file every call (which you usually do not, in a hot path), use `getId` instead:

```ts
import { getId } from "@developersdigest/promptlock";

const promptId = getId({ template, vars, model, temperature });
// pure function, no I/O, safe to call on every request
```

The full SDK surface is small on purpose:

```ts
register({ template, vars?, model?, temperature? }, { note?, dir? })
getId({ template, vars?, model?, temperature? })
readVersion(id, { dir? })
listVersions({ dir? })
diffVersions(a, b)
```

Five functions. No hidden state. No daemon. The `dir` option lets you point at a different artifact directory if you want per-environment storage, but the default `.promptlock/` is what most projects should ship with.

## A pattern that works

The workflow we have settled on for our own apps looks like this:

1. Treat every prompt template as a file, even one-liners. Read it with `fs` rather than embedding it as a string literal.
2. Call `getId` next to the LLM call. Pass the id into logs.
3. Run `promptlock add` whenever you intentionally change a prompt. Commit `.promptlock/`.
4. Add a CI check that diffs the registered ids against the ones the code computes. If they do not match, a prompt changed without a corresponding artifact, and the build fails.

That last step is the one that turns Promptlock from a logging convenience into a real guardrail. Without it, prompts can still drift silently. With it, a prompt change is no longer reviewable in passing. It shows up as a new file in the PR, with a diff a reviewer can read.

## What Promptlock isn't

It is worth being direct about scope, because the LLM tooling space is full of products that promise a lot and deliver a dashboard.

Promptlock v0.1 is local-only. There is no cloud sync, no shared registry, no team dashboard. If you want a hosted prompt registry across multiple repos, this is not it yet.

It does not run evals. It records the prompt that produced an output, but it does not score the output. You bring your own eval harness. The roadmap includes pluggable eval-on-change, but that is not in this release.

It does not post PR comments. There is no GitHub App today. We use it ourselves and run the diff manually in code review. A GitHub App that watches `prompts/**`, `**/SKILL.md`, and `CLAUDE.md` files and comments diffs on PRs is the next thing on the roadmap, but not shipped.

It does not template variables for you. Promptlock hashes the variable schema but does not render. Use whatever templating you already have, whether that is plain `String.replace`, mustache, or Handlebars.

The point of v0.1 is to nail the primitive: a deterministic, content-addressable id and a diff-able artifact. Everything else is layered on top.

## Why this is the right shape

Versioning prompts gets debated in two camps. One camp wants a full prompt management platform with web UI, branches, A/B tests, and a hosted runtime. The other camp says "just put the prompt in git." Both are partially right.

Putting the prompt in git is necessary but not sufficient. A whitespace change in a system prompt is technically committed, but the diff buries it inside an unrelated change to a template literal. Reviewers miss it. A platform fixes that, but at the cost of pulling production-critical state out of your repo and into a vendor.

Promptlock takes the middle path. The artifact lives in your repo, next to the code, in a format git already knows how to diff. The id is deterministic, so anyone with the same template can verify the version locally. The tool is a CLI plus five functions, so you can rip it out in an afternoon if it stops being useful.

If you have written about [DESIGN.md as the design system file agents actually read](/blog/design-md-for-ai-agents), this is the same idea applied to prompts. Production-critical context belongs in the repo, in a format that is both human-readable and machine-checkable. Drift becomes a reviewable change instead of a silent regression.

## Try it

```bash
npx @developersdigest/promptlock add prompt.md \
  --model claude-opus-4-7 --temperature 0.2 \
  --vars '{}' --note "first registration"
```

That single command writes one JSON file. Commit it, and your prompts have an audit trail for the first time. From there, wire the SDK into your call sites and add the CI check.

If you want to see how Promptlock fits next to the rest of the LLM tooling stack, the [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) and the [tool comparison hub](/compare) are good next reads.

The repo is private during the v0.1 polish window. Public release will follow once the GitHub App and eval-on-change pieces land. Until then, this post is the spec.


Six More Tools for the Agent Infrastructure Stack
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The Other Half of the Stack

A couple of weeks ago we [announced ten internal tools](/blog) we were spinning out of the DD portfolio. The first six got their own write-ups: SkillForge CI and Cost Tape in [the small devtools post](/blog/skillforge-ci-and-cost-tape), MCP Lens in [the MCP servers roundup](/blog/best-mcp-servers-2026), TraceTrail in [the local OTel post](/blog/dd-traces-local-otel), Hookyard in [the hooks explainer](/blog/claude-code-hooks-explained), and PromptLock in [the prompt injection post](/blog/prompt-injection-open-source).

Those six were about authoring, observing, and securing agent work. Useful, but only half the picture. The other half is what happens around the agent: how you measure whether it actually works, how the work it produces gets seen, and how the daily ergonomics feel when you live inside [Claude Code](/blog/what-is-claude-code-complete-guide-2026) for eight hours.

That is what these next six fill in. Validation, distribution, and ergonomics. None of them are glamorous. All of them solve a problem we kept hitting often enough that writing the tool was cheaper than tolerating the friction. They are private to the DD portfolio for now, but the patterns travel.

If you missed the [first announcement](/compare), the short version is: we run a lot of small Next.js apps, a lot of Claude Code skills, and a lot of MCP servers. Tooling has to scale to that. Here is the second half.

## dd-ga: Drift Doctor for Google Analytics

### The problem

Twenty-four small apps, all supposedly wired to the same GA4 property. In practice, half of them have hardcoded measurement IDs in three different files, two are missing the snippet entirely, and one is sending page views but no custom events. You only notice when the dashboard goes quiet.

### What it does

`dd-ga` audits a [Next.js](/blog/nextjs-ai-app-stack-2026) repo (or a glob of them) for GA wiring drift. It looks for hardcoded IDs that should be env vars, missing snippets, inconsistent helper paths, and instrumentation that captures page views but no conversion events. Output is human-readable by default, JSON when you pipe it into something else.

### Install

```bash
git clone git@github.com:developersdigest/dd-ga.git
cd dd-ga && node bin/dd-ga.js --help
```

### Sample run

```bash
$ node bin/dd-ga.js audit-all '/Users/j/Developer/dd-*' --quiet
24 repos audited, 7 with findings, 2 errors (missing-snippet)
```

Exit code is non-zero on `error`-severity findings, so it slots into a pre-commit hook or a nightly cron without ceremony.

### Honest limits

Next.js only. The rules are tuned for our App Router conventions. If you put your GA helper somewhere weird it will probably miss it. Treat it as a sanity check, not a compliance tool.

## dd-utm: One-Prompt UTM Builder

### The problem

Every time a video ships, we paste the same URL into six places: YouTube description, X, LinkedIn, Threads, Bluesky, the newsletter. Each one wants a slightly different UTM tag. Done by hand, half the campaigns end up untagged or, worse, tagged inconsistently enough that the analytics view is useless.

### What it does

`dd-utm` is a CLI that builds canonical UTM links from templates. Each template encodes the source, medium, and default content slug for one distribution channel. You pass a URL and a campaign slug; it spits out the tagged URL and copies it to your clipboard.

### Install

```bash
cd dd-utm && npm link
```

### Sample run

```bash
$ dd-utm https://devdigest.tv/blog/prompt-versioning-with-promptlock --template youtube --campaign launch-promptlock
https://devdigest.tv/blog/prompt-versioning-with-promptlock?utm_source=youtube&utm_medium=video&utm_campaign=launch-promptlock&utm_content=description
```

Templates ship for youtube, x, linkedin, threads, bluesky, and newsletter. Free-form mode is there too if you need a one-off.

### Honest limits

There is no link shortener, no click tracker, no dashboard. It is a string-builder. The whole point is that it does one thing and does not require a browser tab open to a SaaS.

## subagent-studio: Visual Designer for Claude Code Agents

### The problem

Subagent files (`.claude/agents/*.md`) are simple markdown with frontmatter, but the rules for that frontmatter are picky. Kebab-case names, single-line descriptions, comma-separated tool lists, optional model and isolation fields. Hand-writing them works fine until you are designing your tenth one and you keep typoing the description into a multi-line block.

### What it does

Subagent Studio is a small Next.js app with a form-based editor on the left and a live markdown preview on the right. Three starter templates: research, code-reviewer, test-writer. The render contract is a single pure function (`renderSubagent`) so the preview is exactly what gets written. Studio never touches your real `~/.claude/agents/` directory; you copy or download.

### Install

```bash
git clone git@github.com:developersdigest/subagent-studio.git
cd subagent-studio && pnpm install && pnpm dev
```

### Sample flow

Open localhost:3000, pick the research template, edit name and description, toggle the isolation field, copy the rendered markdown into your repo. Frontmatter validation runs on every keystroke so invalid agents never make it out.

### Honest limits

Read-only relative to your filesystem. By design. If you want it to write directly to your skills repo, that is a fork away, but the safer default has saved us from a few accidental overwrites.

## agent-eval-bench: Concurrent Eval Suite Runner

### The problem

Most agent eval setups assume you want a Hugging Face leaderboard. We just want to know whether a prompt change broke our extraction skill before we merge it. YAML in, JSON and a markdown report out, run it in CI.

### What it does

`aeb` runs YAML-defined eval suites concurrently against Claude (or Codex, or [OpenAI](/blog/openai-vs-anthropic-2026)). Cases have a prompt, an optional system message, and a list of scorers: `contains`, `regex`, or a small judge prompt. Reports come out as JSON for diffing and markdown for skimming.

### Install

```bash
pnpm install && pnpm build
export ANTHROPIC_API_KEY=...
```

### Sample run

```bash
$ aeb run examples/basic-suite.yaml --model claude-sonnet-4-6 --concurrency 4 \
    --report report.json --markdown report.md
ran 12 cases, 11 passed, 1 failed (regex-capital), 4.2s wall
```

### Honest limits

No cost tracking yet (Cost Tape covers that next door). The judge scorer is intentionally small; if you want full LLM-as-judge with rubrics, this is not it. We use it to catch regressions, not to publish papers.

## mcpaas: Hosted Runtime for MCP Servers

### The problem

[MCP servers](/blog/complete-guide-mcp-servers) are mostly stdio. Cloud agent clients (claude.ai, Cursor cloud) need an HTTPS endpoint. The gap between "I wrote an MCP server in an afternoon" and "agents on the internet can call it" is annoyingly large.

### What it does

MCPaaS is a single-tenant scaffold that spawns any stdio MCP server as a child process and exposes JSON-RPC over `POST /api/rpc`. Bearer token auth, a small dashboard, deploys to a $5 box. Point it at `npx -y @modelcontextprotocol/server-filesystem /tmp` and you have an HTTP MCP server.

### Install

```bash
cp .env.example .env   # set MCPAAS_SERVER_CMD, ARGS, TOKEN
npm install && npm run dev
```

### Sample call

```bash
curl -s http://localhost:3000/api/rpc \
  -H "authorization: Bearer $MCPAAS_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

### Honest limits

Single-tenant on purpose. One server per deploy. No multiplexing, no per-tool rate limits, no usage metering. If you are running an MCP marketplace this is not the substrate; if you have one MCP server you wrote and want it on the internet by lunch, it is.

## repo-postcard: Satori PNGs for GitHub Repos

### The problem

Every blog post, every video thumbnail, every social share for a tool repo wants the same set of stats arranged the same way: stars, top languages, top contributors, last commit, top issues. Doing it by hand once is fine. Doing it across two dozen DD repos every time something ships is not.

### What it does

`repo-postcard` takes an `org/repo`, hits the GitHub API, and renders a 1200x750 PNG postcard via Satori. Cream background, ink text, pink accent: DD palette, no gradients. Markdown summary mode is there too if you want to embed the same data in a README.

### Install

```bash
pnpm install && pnpm build
export GH_TOKEN=ghp_...
```

### Sample run

```bash
$ node dist/cli.js developersdigest/mcp-lens --out postcard.png
wrote postcard.png (1200x750, 84KB)
```

### Honest limits

Public repos only in practice. Private repo data works if your token has scope, but the visual layout assumes things like contributor avatars are public. Web UI, theming, and batch mode are deferred; the CLI core is solid.

## The Through-Line

These six tools, plus the [first six](/blog/skillforge-ci-and-cost-tape), are not a framework and not a platform. They are a stack of small frictions removed.

Look at the shape, though. The first six were inward-facing: authoring skills (SkillForge), inspecting MCP traffic (MCP Lens), tracing agent calls (TraceTrail), running hooks (Hookyard), defending against prompt injection (PromptLock), and watching spend (Cost Tape). Make the agent do the right thing.

The second six face outward and around. **Validation:** agent-eval-bench tells you whether a change made things better or worse. **Distribution:** dd-utm and repo-postcard make sure work that ships actually gets seen and tracked. **Infrastructure ergonomics:** dd-ga keeps shared analytics honest across a portfolio, mcpaas turns an afternoon's MCP server into something a cloud agent can hit, and subagent-studio makes the per-day act of designing agents pleasant instead of fiddly.

The pattern we noticed writing all twelve: the painful part of running agents at any scale is rarely the model call. It is the connective tissue around the model call. Did the change regress? Did the link get tagged? Did the snippet ship? Did the MCP server get a real URL? That is where days disappear, and that is what these tools claw back.

If you want to dig in, every tool has an entry on the [comparison page](/compare) with install commands and a short demo. The repos are private for now while we shake out the rough edges. If one of them solves a problem you also have, ping us and we will prioritize the public release.

The next post in this series is the one we keep putting off: an honest retro of which of these twelve we still use every week, six months in. Some will not survive the cut. That is the point of building twelve small tools instead of one big one.


Six Paid Products in a Day: DD's Bet on Agent Infra for Small Teams
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

We keep saying it. The agent infra layer for small teams does not exist yet.

Big shops have internal platforms. Solo devs scrape by with shell scripts and a prayer. The middle, the two to ten person team running real agent workloads in production, has nothing built for them. They are gluing together OpenTelemetry, half-finished [MCP servers](/blog/complete-guide-mcp-servers), a Notion doc full of prompts, and a billing alert that fires three days too late.

So today DD shipped six paid products at once. All of them target that exact gap. All of them are $20 a month. The bundle is $50 a month for the lot. There is also a teaser at the bottom for a seventh that is not quite ready to price.

Before the tour, the honest part. Most of these are alpha. Some are still in private repos while we tighten the rough edges. Clerk Billing is not fully wired yet, so for now there is one waitlist link instead of six checkout buttons. We will flip the switch when the plumbing is done. Posting now because shipping public beats polishing in private.

If you want the longer version of how all of this got built in one overnight session, we wrote that up too: [12 tools in one night with Claude Code](/blog/12-tools-in-one-night-with-claude-code).

## The Thesis

Agent infra for small teams. That is the whole pitch.

Not for hyperscalers. Not for hobbyists who can live without observability. For the team that has three agents running on a Hetzner box, a [Claude Code](/blog/what-is-claude-code-complete-guide-2026) workflow that touches production, and zero appetite for paying $400 a month per seat to a vendor that wants a SOC 2 review before they will return your call.

Each product solves one piece. The bundle solves the stack.

## The Six

### 1. agentfs: a filesystem your agents will not break

Agents write to disk. Agents corrupt disk. Agents do it on Tuesday at 3am while you are asleep.

agentfs is a snapshot-aware filesystem layer. Every write goes through a journal. Every agent run gets a checkpoint. When the agent goes off the rails and `rm -rf`'s your `node_modules` for the third time, you roll back in one command. Local first, with a sync mode for teams.

This is the most production-ready of the six. We have been dogfooding it on the DD app farm for two weeks. Public repo coming this week.

Read the deep dive: [Introducing agentfs](/blog/introducing-agentfs).

### 2. Skills Pro

The [DD Skills Marketplace](/blog/claude-code-skills-marketplace-launch) is the free side: a public registry of Claude Code skills, the same way npm hosts packages. Search, install, share.

Skills Pro is the paid layer on top. Private skills for your team. Versioned releases with changelogs. A real CI pipeline that lints, tests, and benchmarks your skills before they ship to your team's machines. Plus the SkillForge runner which compiles new skills from your own codebase. We covered the runner side in the [SkillForge CI and Cost Tape](/blog/skillforge-ci-and-cost-tape) post.

If your team writes more than five skills, the manual approach falls over fast. Skills Pro is the answer.

### 3. Hookyard Pro

[Claude Code hooks](/blog/claude-code-hooks-explained) are powerful. They are also a footgun. One bad pre-commit hook and the agent loops forever burning tokens. One bad post-tool hook and your repo is full of generated junk.

[Hookyard](/blog/claude-code-hooks-with-hookyard) is a hook registry plus runner. The free tier ships the public hooks. Hookyard Pro adds the team layer: private hooks, audit logs of every hook fire, an emergency kill switch when an agent gets stuck in a loop, and quota enforcement so a runaway hook cannot rack up a $400 bill overnight.

This pairs naturally with Cost Tape. Hookyard fires the hook. Cost Tape watches the meter.

### 4. MCPaaS Plus

[MCP](/blog/what-is-mcp) servers are the new lambdas. Everyone is writing them. No one is operating them.

MCPaaS Plus is hosted MCP. You point it at a repo, it spins up the server with auth, rate limits, and structured logs. Plus it ships with [MCP Lens](/blog/mcp-debugging-with-mcp-lens) integration, so when an agent calls a broken tool you get the full request and response, not a vague timeout.

The Plus tier adds private servers, custom domains, and pinned versions. Most teams hit the free tier ceiling within a week of using MCP seriously, so we are pricing the upgrade where it should be: cheap.

### 5. TraceTrail Plus

Agents do weird things. Then they do them again, but only sometimes, and only in production.

[TraceTrail](/blog/agent-replays-with-tracetrail) records every step an agent takes: tool calls, model responses, retries, branch decisions. The free tier keeps seven days. TraceTrail Plus extends retention to ninety days, adds replay (rerun a past trace against a new prompt or model to see what would have changed), and ships diff view so you can compare two runs side by side.

This is the closest thing to a real debugger that exists for agents right now. If you have ever stared at a transcript wondering why the agent picked the wrong file, this is the tool.

Bonus: TraceTrail Plus integrates with [PromptLock](/blog/prompt-versioning-with-promptlock) for prompt versioning, so every replay is tied to the exact prompt revision that ran.

### 6. Cost Tape Cloud

The local Cost Tape CLI tracks token spend across every model, every CLI, every agent. Cost Tape Cloud is the team mode. Centralized dashboard. Per-developer breakdowns. Budget alerts that fire before the bill, not after.

We built this because we lived [the $400 overnight bill](/blog/400-dollar-overnight-bill-agent-finops). Once is a lesson. Twice is a budgeting failure. Cost Tape Cloud makes twice impossible.

If you only buy one product on this list, it pays for itself the first time it stops a bad run.

## The Bundle

Six products, $20 each, equals $120 a month if you buy them separately. The DD bundle is $50 a month, all six included. We can go that low because we are not paying enterprise sales reps and we are not running a marketing department.

The math is simple. If TraceTrail Plus prevents one bad debugging session, it pays for the whole bundle. If Cost Tape Cloud catches one runaway agent, it pays for the year.

The bundle is the right answer for any team running real agent workloads. Buying just one of these is fine, but the products compose. agentfs snapshots a run that TraceTrail recorded that Cost Tape priced that Hookyard kicked off from a hook stored in Skills Pro that called an MCP server hosted on MCPaaS Plus. The whole stack working together is the actual product.

## The Honest Roadmap

This is alpha. Not GA. Not even open beta on most of them. Here is the real status board.

- **agentfs**: closest to GA. Public repo this week. Production ready for solo use, team sync mode is alpha.
- **Skills Pro**: public marketplace is live. The Pro features (private skills, CI runner) are in private repo, working but rough.
- **Hookyard Pro**: free tier public. Pro tier in private alpha with three teams.
- **MCPaaS Plus**: free tier in public beta. Plus tier private, six servers running in production for DD itself.
- **TraceTrail Plus**: TraceTrail OSS is public. Plus features (90 day retention, replay, diff) are in private alpha.
- **Cost Tape Cloud**: local CLI is OSS. Cloud is private alpha, used internally for the DD app farm.

Clerk Billing is not yet wired. We are doing waitlist signups today and converting to paid checkout when billing is ready, which is days, not weeks. Founding members on the waitlist get the bundle at $30 a month for the first year.

Repos go public as each product hits a state we are not embarrassed to ship. Some this week. Some next month. The free tiers ship first. The Pro features unlock as they stabilize.

Want the broader catalog of what we have shipped this week? Check the [ten tools for agent infrastructure](/blog/ten-tools-for-agent-infrastructure) post and the [six more tools](/blog/six-more-tools-for-agent-infrastructure) follow-up. There are a lot more pieces in flight.

If you want the curated list of skills that actually pull their weight inside Claude Code, [the best Claude Code skills of 2026](/blog/best-claude-code-skills-2026) is the right starting point.

## Teaser: Agent Eval Bench Plus

The seventh product is not on the price sheet yet, but it is too useful to leave out.

Agent Eval Bench is a benchmarking harness for your agents. Run a fixed task suite against your current setup. Get pass rates, cost per task, latency, and a regression view across runs. The Plus tier will add custom task packs, scheduled benchmarks, and CI integration so you catch agent regressions before merge.

We are still tuning the eval methodology. Pricing lands when the methodology is honest. Probably $30 a month, probably bundled at $60. Watch for the launch post.

## The CTA

One waitlist link, since Clerk Billing is not live yet:

**[Join the DD Pro waitlist](/pro)**

You pick the bundle or any individual product when checkout flips on. Founding rate locks in for everyone on the list before launch day. We will email when each product is ready to use, in the order they ship, smallest blast radius first.

This is the bet. Agent infra for small teams. Six products today, more shipping every week. If you have been waiting for someone to build the layer that sits between "I wrote a shell script" and "I have a platform team," this is it.

Ship with us.


Two Small Devtools: SkillForge CI and Cost Tape
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## Small Tools Compound

The big AI tooling debates get all the airtime. Which model. Which harness. Which framework. Meanwhile the thing that actually slows you down on a Tuesday afternoon is something dumb: a SKILL.md file that quietly bloated past the token budget and stopped loading, or a forgotten background agent that has been burning [OpenAI](/blog/openai-vs-anthropic-2026) credits since lunch.

These are not glamorous problems. They are the small frictions that compound across a week of agent work, and they tend to be invisible until they hurt.

This week we shipped two tools to fix exactly those frictions. Both are tiny. Both live in the part of the workflow nobody writes blog posts about. We are writing one anyway, because if you run [Claude Code](/blog/what-is-claude-code) every day you probably want them too.

The pairing is intentional. **SkillForge CI** keeps your skills repo from rotting. **Cost Tape** keeps your spend visible while you ship. Together they cover two of the easiest ways to lose a day to invisible drift.

## SkillForge CI: Lint Your SKILL.md Files

### The problem

If you have written more than five [Claude Code skills](/blog/why-skills-beat-prompts-for-coding-agents-2026), you have probably hit at least one of these:

- A SKILL.md crept past the soft token budget and stopped getting auto-loaded.
- Frontmatter description was too short, so the skill never matched the user's intent.
- A `./scripts/foo.sh` reference in the body pointed at a file that got renamed three commits ago.
- A skill folder name no longer matched the `name:` in frontmatter, so the registry got confused.

Skills fail silently. There is no compiler. The agent just quietly stops loading the file and you do not notice until you wonder why a behavior you wired up last month is gone.

SkillForge CI is a pure linter for SKILL.md files. It checks the things that bite you in production:

- File size against a hard cap (50 KB by default).
- Estimated token count, with a soft warning above 2,000.
- Required frontmatter fields, including a description length sanity check.
- Skill name pattern (lowercase slug, optional `namespace:name` form).
- Folder name matching the skill name.
- Broken local file references inside the body.

It is a single Node script with one runtime dependency (`gray-matter`) and no I/O side effects beyond reading. The whole thing is about 130 lines in `lib/lint.js` plus a 40-line CLI wrapper in `bin/skillforge.js`, which means you can read it end to end before deciding whether to trust it in CI. We deliberately kept it boring. Linters that try to do too much become impossible to extend, and skills move fast enough that the rules are going to keep changing.

The defaults are tuned to where skills actually start failing in practice: a 50 KB hard cap (well above any real skill we have written), a 2,000 token soft warning (where [Claude Code](/blog/what-is-claude-code-complete-guide-2026) starts deprioritizing auto-load), and a 20-character minimum description (anything shorter and the skill almost never matches user intent).

### Install and run

```bash
npx skillforge-ci-cli ~/.claude/skills
```

Or wire it into a repo:

```bash
npm install -D skillforge-ci-cli
npx skillforge .
```

Output looks like this:

```
skillforge: scanned 42 SKILL.md file(s) under ~/.claude/skills
  ok    ~/.claude/skills/commands/qa/SKILL.md  (~480 tok)
  warn  ~/.claude/skills/commands/handoff/SKILL.md  (~2380 tok)
        warn:  Estimated 2380 tokens (>2000). Consider splitting or trimming.
  FAIL  ~/.claude/skills/commands/old-thing/SKILL.md  (~120 tok)
        error: Frontmatter must include a string `description`.
        warn:  Broken local reference: ./scripts/run.sh

1 error(s), 2 warning(s)
```

Exit code is non-zero on errors, so it drops straight into a GitHub Action. There is also a `--json` flag for piping into a PR-comment script.

### Roadmap honesty

This is v0.1. The token estimate is a 4-chars-per-token approximation, not a real tokenizer. There is no autofix. The GitHub Action wrapper is in `dist/` but Org Actions billing is currently blocking the public release on our side, so the action runs red regardless of code health for the moment. CLI use is unaffected.

## Cost Tape: LLM Spend in Your Status Bar

### The problem

If you run more than one Claude Code session, plus a Codex tab, plus a background agent or two, you lose track. The first time you really notice is a billing email. We have written about [the $400 overnight bill](/blog/400-dollar-overnight-bill-agent-finops) before. The fix is not to stop running agents. The fix is to make the cost visible the way `git status` is visible: always there, in your peripheral vision, ambient.

Cost Tape is a tiny VS Code extension that puts your live LLM API spend in the status bar:

```
$3.60 today / $96.65 mtd
```

Click it for a per-provider breakdown. That is the whole product.

### How it works

It polls the official cost endpoints every five minutes (configurable, minimum 60 seconds) and caches results for 60 seconds in memory so it does not hammer anything:

- [Anthropic](/blog/anthropic-vs-openai-developer-experience): `GET /v1/organizations/cost_report` (admin key, `anthropic-version: 2023-06-01`).
- OpenAI: `GET /v1/organization/costs` (admin key bearer auth).

You bring your own admin keys. Workspace or per-call API keys do not have access to usage endpoints. You will need:

1. Anthropic Admin key from Console → Settings → Admin Keys (`sk-ant-admin-...`).
2. OpenAI Admin key from Platform → Organization → Admin keys (`sk-admin-...`).

### Install

The .vsix lives in the repo. Install with:

```bash
code --install-extension cost-tape.vsix
```

Then in VS Code settings:

```jsonc
{
  "costTape.anthropicAdminKey": "sk-ant-admin-...",
  "costTape.openaiAdminKey": "sk-admin-...",
  "costTape.providers": ["anthropic", "openai"],
  "costTape.pollIntervalSeconds": 300,
  "costTape.hideWhenZero": false
}
```

Either key alone is fine. Cost Tape only polls providers that are configured.

Two commands ship with it:

- `Cost Tape: Refresh Now` clears the cache and re-polls.
- `Cost Tape: Show Details` opens a modal with the per-provider split.

_Status-bar screenshots: TODO once we have a few weeks of real data on the tape._

### Roadmap honesty

v0.1 is the status-bar tape and the modal. That is it.

The biggest known limitation: Anthropic does not expose a public per-API-key usage endpoint, so Cost Tape reports org-wide Anthropic spend. If you run multiple projects against one org, you cannot split them yet. We are watching the admin API changelog and will wire per-key attribution the moment it ships.

Coming later: a webview dashboard with charts, multi-account support, and shareable spend snapshots. Today it is a tape. The tape is enough.

### Privacy

Cost Tape only talks to `api.anthropic.com` and `api.openai.com`. Your admin keys are stored in VS Code settings (machine-scoped) and never leave your machine. No telemetry, no analytics, no third-party calls. The whole extension is roughly 800 lines of TypeScript split between two provider files, `lib/providers/anthropic.ts` and `lib/providers/openai.ts`, and a thin status-bar renderer. If you want to read it before installing, the source is the docs.

## Both in the Daily Flow

Here is how these two land in a real workday.

You open VS Code. Cost Tape sits in the bottom right and tells you yesterday's runaway agent cost you nine bucks, not ninety. Good. You open a skills repo, run `npx skillforge .` from the integrated terminal, and find one warning on a skill you edited last week. Fix it in two minutes. Push. Move on.

That is the entire pitch. Neither tool is exciting. Neither tool will be the headline of a launch week. But both replace a recurring small failure with a thirty-second check, and over a month that adds up to real time.

If you are interested in the rest of the small-tools sweep we shipped this week, the other five are in our [ten tools for agent infrastructure announcement](/blog/ten-tools-for-agent-infrastructure) and live tutorials. And if you are still picking your AI coding stack, the [compare page](/compare) has the side-by-side.

The point of all of this is not the tools individually. The point is that developer hygiene is mostly small tools used consistently. Lint your skills. Watch your spend. Then go back to building the interesting thing.


10 Tools We Built for Agent Infrastructure
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## The gap nobody is filling

The big agent platforms ship for enterprise. The open-source frameworks ship for hobbyists. In the middle sits a small but growing group of teams running agents in production every day - two engineers, four engineers, ten engineers - who need real tooling but cannot stomach Langsmith pricing or wire up Datadog for a side project. That is the [gap](/blog/agentic-dev-stack-2026) we keep falling into ourselves at Developers Digest. So over the past week we built ten tools for it, all private for now, all aimed at the same thesis: agent infrastructure for small teams is a real category, and the surface area is much wider than observability alone.

Here is what dropped, why each one exists, and how the pieces compose.

## The directory

### 1. SkillForge CI

[Claude Code skills](/blog/why-skills-beat-prompts-for-coding-agents-2026) are markdown files. Markdown is forgiving. That is the problem. A typo in a skill's frontmatter, a malformed trigger line, a missing description - none of it surfaces until the skill silently fails to load on someone else's machine. SkillForge CI is a GitHub Action that lints every `SKILL.md` in a repo on push. It checks frontmatter shape, validates triggers, flags drift between the description line and what the skill actually does, and refuses to merge skills with broken script references.

Install is one workflow file. The action is private today; once we have a stable rule set we will open it up.

```yaml
- uses: developersdigest/skillforge-ci@v0
```

If your team shares skills across repos, this is the seatbelt. Note that as of today Org Actions billing is paused for us, so CI is red regardless - the action runs locally via `act` until that clears.

### 2. MCP Lens

[MCP servers](/blog/complete-guide-mcp-servers) communicate over stdio. When something breaks, you see nothing. MCP Lens is a transparent proxy that sits between your MCP host and any server, captures every JSON-RPC frame in both directions to a JSONL log, and serves a local inspector at localhost:4040. We call it Wireshark for MCP because that is exactly what it is.

```bash
mcp-lens --ui -- npx -y @modelcontextprotocol/server-filesystem /tmp
```

The full walk-through is in the [MCP Lens debugging tutorial](/blog/mcp-debugging-with-mcp-lens). If you have ever watched a Claude Code tool call hang for forty seconds with no idea why, this is the tool you wished you had. Replay, schema-diff, and shareable session links are next.

### 3. TraceTrail

Once you can capture an agent run, you want to share it. TraceTrail is Loom for agent runs. Upload a [Claude Code](/blog/what-is-claude-code-complete-guide-2026) JSONL transcript, get a public read-only replay URL with a stepped timeline, tool calls expanded inline, costs per step, and a permalink anyone can open without an account. Auth-gated upload, public replay - same shape as Loom.

```bash
curl -F "file=@session.jsonl" https://tracetrail.dev/api/upload
```

The full walk-through is in the [TraceTrail tutorial](/blog/agent-replays-with-tracetrail). We are using it internally for bug reports, demos, and onboarding. It is the one tool on this list that already feels indispensable a week in.

### 4. dd-ga (Drift Doctor for Google Analytics)

We run [twenty-four sites](/apps) under the Developers Digest umbrella. Every one needs Google Analytics. Every one ends up with a slightly different GA wiring - hardcoded measurement IDs in some, helper paths inconsistent across others, a few that only fire page views and miss events entirely. dd-ga audits a Next.js repo or a glob of them, flags the drift, and exits non-zero on errors so it can run in CI.

```bash
node bin/dd-ga.js audit-all '/Users/j/Developer/dd-*'
```

It found three sites with broken GA in our portfolio the first time we ran it. Not glamorous. Extremely useful. Same pattern will work for Sentry, sitemap, robots, OG, llms.txt - every shared-infra concern that silently rots across a portfolio of small apps.

### 5. Cost Tape

Every developer running agents has had the moment where they look at the [Anthropic](/blog/anthropic-vs-openai-developer-experience) dashboard at the end of a session and feel something cold in their stomach. Cost Tape is a VS Code status bar extension that polls the Anthropic and OpenAI org cost endpoints every five minutes and renders a tape: `$3.60 today / $96.65 mtd`. Click it for a per-provider breakdown. Bring your own admin key.

```jsonc
{
  "costTape.anthropicAdminKey": "sk-ant-admin-...",
  "costTape.openaiAdminKey": "sk-admin-..."
}
```

It is the cheapest possible answer to "how much am I spending right now." Webview dashboards and shareable charts come later. Pairs naturally with our [overnight bill post-mortem](/blog/400-dollar-overnight-bill-agent-finops).

### 6. Hookyard

Claude Code hooks are powerful and almost nobody uses them, because writing one means hand-editing `~/.claude/settings.json` and getting the JSON shape exactly right. Hookyard is a curated directory of hooks plus a CLI installer that patches your settings file idempotently with a `.bak` backup before each write. Think `npm install` but for hooks.

```bash
npx hookyard install obsidian-auto-commit
```

The full walk-through is in the [Hookyard tutorial](/blog/claude-code-hooks-with-hookyard). The directory site is browsable, every hook is typed, and the installer never touches your real settings without a snapshot. We are seeding it with the hooks from our own stack and opening submissions once the schema settles.

### 7. Promptlock

Your prompts are production code, but most teams ship them as raw markdown with no version IDs, no diffs, no provenance. A whitespace tweak in a system prompt can shift eval scores by ten points and you would never know which commit did it. Promptlock turns every prompt into a content-addressable artifact - twelve-character ID, model, temperature, vars, note - that you can commit, diff, and roll back.

```bash
promptlock add prompt.md --model claude-opus-4-7 --temperature 0.2
```

The full walk-through is in the [Promptlock versioning tutorial](/blog/prompt-versioning-with-promptlock). Cloud sync, eval suite integration, and PR-comment diffs are intentionally out of scope for v0.1. Step one is just giving prompts a stable identity. Everything else builds on that.

### 8. dd-utm

The most embarrassing reason for clean attribution data on your video distribution: we kept forgetting to tag links. Different videos used different UTM conventions, half the social posts had no UTM at all, the newsletter had its own scheme. dd-utm is a one-prompt CLI that standardizes UTM tagging across YouTube, X, LinkedIn, Threads, Bluesky, and the newsletter, with templates for each platform.

```bash
dd-utm https://devdigest.tv/blog/prompt-versioning-with-promptlock --template youtube --campaign launch-promptlock
```

Tiny tool. Solved a real recurring annoyance the day we shipped it. The principle generalizes: most "agent infrastructure" is just removing friction from work the team is already doing.

### 9. Subagent Studio

Claude Code subagents live in `.claude/agents/*.md` files with strict frontmatter rules. Get the kebab-case wrong, embed a newline in the description, list a tool that does not exist - the agent silently fails to load. Subagent Studio is a visual designer with a form-based editor on the left and a live preview on the right. Three starter templates: research, code reviewer, test writer. Copy or download the rendered markdown - it never writes to your real `~/.claude/agents/` directory.

```bash
pnpm dev   # http://localhost:3000
```

If SkillForge CI is the seatbelt for skills, Subagent Studio is the seatbelt for agents. Lower the floor, fewer broken configs, more people shipping agent fan-outs that actually work.

### 10. Agent Eval Bench

The last piece. Once you have versioned prompts, captured runs, and observability tape, you need a way to ask "did this change make things better." Agent Eval Bench is a deterministic eval suite runner. Define test cases as YAML, run them concurrently against any model, score with assertions or a small judge prompt, write a report.

```bash
aeb run examples/basic-suite.yaml --model claude-sonnet-4-6 --concurrency 4
```

Scorers today are `contains`, `regex`, and a judge prompt. JSON and Markdown reports out of the box. It is the smallest possible thing that lets you catch a regression in a prompt change before it ships. Pairs directly with Promptlock - lock the prompt, eval the lock.

## The through-line

Look at the list again and the shape gets clearer.

**Observability:** MCP Lens captures the wire, TraceTrail shares the run, Cost Tape watches the spend. You cannot improve what you cannot see, and the existing tools either cost too much or assume too much.

**Skills and hooks:** SkillForge CI lints, Hookyard installs, Subagent Studio designs. These are the extension surfaces of Claude Code, and right now there is no tooling around them at all - everyone is hand-editing markdown and praying.

**Prompts and evals:** Promptlock versions, Agent Eval Bench scores. Together they let a small team treat prompts like code: identity, diffs, regressions caught in CI.

**Portfolio infrastructure:** dd-ga audits drift, dd-utm standardizes outbound. The boring connective tissue that keeps a portfolio of small apps coherent without a platform team.

That is the thesis. Agent infrastructure for small teams is not one tool, it is a stack - and most of the stack does not exist yet because the big platforms are too busy chasing enterprise and the open-source frameworks are too busy chasing star counts. The middle is wide open. The [agent ecosystem report](/blog/agentic-dev-stack-2026) makes the case in more detail.

## Roadmap honesty

None of these are production-ready. None of them are public yet. Every one is at v0.1 or earlier and was built on a single overnight push, which is exactly the right amount of stress test for a thesis like this - if a tool does not survive its own author using it for a week, it does not get released.

The plan from here:

- **Eat our own dog food for two weeks.** Every tool gets used internally on the [Developers Digest portfolio](/apps) and on real work. Tools that do not survive get killed.
- **Open the four with tutorials first** - Promptlock, TraceTrail, Hookyard, MCP Lens - because each one already has a written narrative we are willing to defend in public.
- **Open the rest only when they earn it.** Cost Tape needs polish on the click-through dashboard. Subagent Studio needs templates. Agent Eval Bench needs more scorers. SkillForge CI needs a stable rule set. dd-ga and dd-utm are useful internal tools that may stay internal.

If you want to see how these compare to the alternatives, the [tools comparison page](/compare) covers the existing landscape. We will update it as each of these ten goes public.

Comments and DMs welcome. The thesis is the part we want to be wrong about, fast.


10 Trending AI Dev Tools, Week of April 28 2026
Developers Digest — Tue, 28 Apr 2026 00:00:00 GMT

## A real April, not a recap of last quarter

The last 30 days were the loudest month of 2026 so far. Anthropic shipped Opus 4.7. OpenAI shipped GPT-5.5 and rebuilt the Codex CLI. Google shipped Gemini 3 Pro and Antigravity. The [Claude Code skills](/blog/why-skills-beat-prompts-for-coding-agents-2026) ecosystem went from "neat side trick" to a mainstream extension model with thousands of public skills. And on the open-source side, two repos (Andrej-karpathy-skills and Hermes Agent) absorbed most of the GitHub Trending oxygen.

Here are the ten tools, models, and repos worth your attention this week, with the commands and links you actually need.

## 1. Claude Opus 4.7

Released April 16, 2026. On Anthropic's 93-task internal coding benchmark, [Opus 4.7 lifted resolution by ~13% over Opus 4.6](https://www.anthropic.com/news/claude-opus-4-7), including four tasks neither Opus 4.6 nor Sonnet 4.6 could solve. Pricing stays at $15 / $75 per million tokens. Available in Claude apps, the API, [Amazon Bedrock](https://aws.amazon.com/blogs/aws/introducing-anthropics-claude-opus-4-7-model-in-amazon-bedrock/), Vertex AI, and Microsoft Foundry.

Pin it in [Claude Code](/blog/what-is-claude-code-complete-guide-2026):

```bash
claude --model claude-opus-4-7
```

Or set it as the default in `~/.claude/settings.json`:

```json
{
  "model": "claude-opus-4-7"
}
```

## 2. OpenAI GPT-5.5 (and the new Codex CLI)

GPT-5.5 hit the API on April 24, 2026. [OpenAI's positioning](https://openai.com/index/introducing-gpt-5-5/) is "smarter and more token-efficient than GPT-5.4" - and inside Codex specifically, it produces better diffs with fewer tokens.

The bigger story is Codex CLI itself. Recent [Codex changelog entries](https://developers.openai.com/codex/changelog) added Unix socket transport for the app-server, sticky environments, remote plugin install, automatic reviewer agents for risky approvals, and `codex exec --json` reasoning-token reporting. Try the new browser hand-off:

```bash
codex
> use the browser to reproduce the layout bug on localhost:3000
```

If you have not picked sides yet, our [Claude Code vs Codex App breakdown](/blog/claude-code-vs-codex-app-2026) is still mostly accurate - just bump every Codex bullet up a notch.

## 3. Gemini 3 Pro and Google Antigravity

Google released `gemini-3-pro-preview` on April 22, 2026 with strong agentic and coding behavior. The [Gemini 3 developer guide](https://ai.google.dev/gemini-api/docs/gemini-3) covers the new tool-use loop. The more interesting piece is [Google Antigravity](https://blog.google/products/gemini/gemini-3/), an agentic IDE-adjacent platform where Gemini 3 plans and executes end-to-end tasks while self-validating.

Gemini 3 Flash arrived a few days later and is already wired into the [Gemini CLI](https://developers.googleblog.com/gemini-3-flash-is-now-available-in-gemini-cli/):

```bash
gemini -p "summarize the diff in HEAD~1..HEAD"
```

## 4. Claude Haiku 4.5

If you missed it earlier this quarter, [Haiku 4.5](/blog/claude-haiku-4-5) is still the price/performance pick: roughly Sonnet 4-tier coding at one third the cost and twice the speed. Pricing is $1 / $5 per million tokens. Worth slotting in for cheap parallel sub-agents while reserving Opus 4.7 for the planner.

## 5. Andrej-karpathy-skills

The breakout repo of late April. As covered in [GitHub Trending Weekly](https://www.shareuhack.com/en/posts/github-trending-weekly-2026-04-22), it added roughly 44k stars in a week and triggered the wider Claude Code skills ecosystem boom. The skills are pedagogical and surprisingly good as starter material. Drop them into `~/.claude/skills/` and they show up automatically.

```bash
gh repo clone andrej-karpathy/skills ~/.claude/skills/karpathy
ls ~/.claude/skills/karpathy
```

## 6. The Claude Code skills marketplace

[claudemarketplaces.com](https://claudemarketplaces.com/) and the open-source [claude-code-plugins-plus-skills](https://github.com/jeremylongshore/claude-code-plugins-plus-skills) (423 plugins, 2,849 skills, 177 agents) became real this month. A plugin bundles skills, MCP servers, slash commands, and sub-agents into one installable unit, which is the right granularity. If you have not started writing your own, our [Claude Code skills guide](/blog/claude-skills-breaking-llm-memory-barriers) is the fastest way in.

## 7. Hermes Agent

[Hermes Agent](https://www.shareuhack.com/en/posts/github-trending-weekly-2026-04-13) hit 65k stars and added 32k of those in a single week earlier in April. It is one of the more enduring agent frameworks on Trending - good defaults, simple Python API, and plays nicely with MCP servers. Worth a look if LangGraph feels heavy.

## 8. EvoMap and self-evolving agents

EvoMap and [GenericAgent](https://github.com/lsdefine/GenericAgent) pushed self-evolving agents into mainstream attention. EvoMap's "Genome Evolution Protocol" lets agents mutate and select prompts, tools, and policies over time. GenericAgent grows a skill tree from a 3.3k-line seed and claims roughly 6x lower token use than static frameworks. Both are early, both are interesting, neither is production-ready yet.

## 9. MarkitDown

Microsoft's [MarkitDown](https://github.com/microsoft/markitdown) is still adding ~7k stars per week. It converts PDF, Word, Excel, PowerPoint, and HTML to clean Markdown so any LLM pipeline can ingest them. It's the boring, useful kind of tool you should already have installed:

```bash
pipx install markitdown
markitdown report.pdf > report.md
```

This is the kind of unglamorous glue that quietly shows up in every serious agent stack.

## 10. The visual builders, still huge

Three of the top five AI repos on GitHub are visual workflow builders: [Langflow](https://github.com/langflow-ai/langflow) at 146k stars, [Dify](https://github.com/langgenius/dify) at 136k, and [Flowise](https://github.com/FlowiseAI/Flowise) at 51k. [n8n crossed 180k stars](https://blog.bytebytego.com/p/top-ai-github-repositories-in-2026). They are not what you'd reach for to build a hard agent product, but they remain the fastest way to wire a prototype that calls real APIs and real models.

## What to actually do this week

If you have one hour, do three things:

1. Switch your default Claude Code model to Opus 4.7 and your sub-agent model to Haiku 4.5. This is the highest-value change of the month for most repos.
2. Update [Codex CLI](/blog/openai-codex-guide) (`npm i -g @openai/codex@latest`) and try `codex exec --json` against a small repo to see GPT-5.5's reasoning-token output.
3. Drop one community skill into `~/.claude/skills/` and watch how Claude picks it up automatically. Once you do this once, you write your own skills the next day.

The rest of the list is worth keeping tabs on, but those three changes alone will move how your agents behave on Monday.

For deeper picks see [Best MCP servers 2026](/blog/best-mcp-servers-2026) and [Best CLI tools for AI development 2026](/blog/best-cli-tools-for-ai-development-2026).


The Claude Design Moment: AI Design Skills Just Got Their Breakout Week
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT
## Update: May 2026

Two weeks after the initial breakout, these repos have continued compounding. Current star counts as of May 6:

| Repo | Launch Week | Now | Growth |
|------|-------------|-----|--------|
| [huashu-design](https://github.com/alchaincyf/huashu-design) | 4,857 | 12,257 | +152% |
| [open-codesign](https://github.com/OpenCoworkAI/open-codesign) | 1,520 | 4,925 | +224% |
| [awesome-claude-design](https://github.com/VoltAgent/awesome-claude-design) | 1,282 | 2,002 | +56% |
| [cc-design](https://github.com/ZeroZ-lab/cc-design) | 603 | 705 | +17% |

The combined total is now **19,889 stars** - more than double the launch week. The pattern described below is holding.

---

## Something kicked off on GitHub this week

If you checked the trending repos for new projects created in the past seven days, a pattern should have jumped out. Four of the top fifteen new repos with more than 100 stars share a theme.

- [huashu-design](https://github.com/alchaincyf/huashu-design) - HTML-native design skill for Claude Code with 20 design philosophies and animation export.
- [open-codesign](https://github.com/OpenCoworkAI/open-codesign) - Open-source "Claude Design" alternative that imports Claude Code and Codex projects.
- [awesome-claude-design](https://github.com/VoltAgent/awesome-claude-design) - Curated list of 68 ready-to-use design system inspirations in `DESIGN.md` format.
- [cc-design](https://github.com/ZeroZ-lab/cc-design) - High-fidelity HTML design and prototype guidance skill.

Combined, that was **over 8,000 stars in under a week** across four projects that all orbit the same idea. The cluster is loud enough that ignoring it would miss a real shift in how developers are using [Claude Code](/blog/what-is-claude-code-complete-guide-2026).

## Quick take if you are here to ship better UI

- Want a repeatable workflow you can run inside any repo? Start with [Create Beautiful UI with Claude Code](/blog/create-beautiful-ui-claude-code).
- Want your design preferences to travel with the repo so any agent reads them first? Use [Design.md for AI Agents](/blog/design-md-for-ai-agents).
- Want the fastest map of what to try next? Start with the [best Claude Code skills directory](/blog/best-claude-code-skills-2026) and the [AI tool comparisons hub](/compare).

## What these projects actually do

The shared core is: [AI agents](/blog/ai-agents-explained) are now doing design, but the default output looks like slop. These projects are the anti-slop layer.

A few weeks ago we covered the [AI design slop study](/blog/ai-design-slop-and-how-to-spot-it) that found 21 percent of Show HN pages trigger five or more of fifteen common "generated by a chat interface" design patterns. The community apparently read the same study and started shipping the countermove.

**Huashu-design** takes the most opinionated approach. It ships a `SKILL.md` with twenty encoded design philosophies, a five-dimension review system, and animation pipelines that export to MP4. The pitch is "type a sentence, hit enter, get a finished design." The examples in the README - Gallery ripples, brand reveal animations, interactive app prototypes - are hand-done-quality-but-not-hand-done. Every asset in the README is generated by the skill itself. That is a confidence signal.

**open-codesign** is the open-source twin of [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s (hypothetical?) Claude Design. It imports your existing Claude Code or Codex project and scaffolds design work from the repo context. One-click onboarding is the feature.

**awesome-claude-design** is a curated list - sixty-eight `DESIGN.md` reference documents you can drop into your repo. Same pattern as the `awesome-*` genre, but the payload is design system specifications instead of library links.

**cc-design** rounds out the cluster with high-fidelity HTML prototyping focused specifically on guidance for AI agents. Less opinionated than huashu, more extensible than awesome-claude-design.

## The common thesis

All four projects share a thesis that is new enough to be worth stating out loud.

**Design is a `SKILL.md` problem.** The encoded opinion belongs in a file the agent reads before it generates. Not a prompt you paste each time. Not a template library. A standing instruction set that travels with your repo and loads automatically when the agent sees a design task.

This is the same insight that drove context engineering more broadly: the lever that actually moves AI output quality is not a better prompt, it is better pre-loaded context. Design was the last creative domain to catch on because the output is visual and harder to grade programmatically. These four projects are the result of the domain finally catching on.

A secondary thesis underneath: **opinionated defaults beat infinite flexibility**. Every one of these projects ships a set of concrete design choices. Huashu has its twenty philosophies. Awesome-claude-design lists specific design systems. CC-design picks a stance on fidelity. Open-codesign assumes a specific import flow. The anti-pattern they are all avoiding is the "you can make anything" tool that produces nothing memorable.

## Why this week specifically

A few factors probably compounded to make this the breakout week.

First, the AI slop study gave the community a vocabulary. Once "colored left borders are almost as reliable a sign of AI-generated design as em dashes" becomes a quotable line, the incentive to ship something that is not that goes up fast.

Second, Claude Code's skill marketplace crossed a critical mass of working examples. Developers have seen what a good `SKILL.md` looks like in other domains - code review, testing, migration - and are now porting the pattern to design.

Third, Zed's [parallel agents launch](/blog/zed-parallel-agents-first-editor-making-it-native) earlier this week normalized the idea of per-thread specialized agents. A thread running huashu-design in parallel with a thread running feature-dev is a natural composition.

All three signals fed into each other. The result is a week where "Claude Design" became a thing.

## What to do if you are building with AI

Three practical takeaways.

**Install one of these skills and try it.** The installation pattern is typically one line:

```bash
npx skills add alchaincyf/huashu-design
```

The friction is low and the delta on your design output is measurable. Even if you do not adopt it long-term, seeing what a well-opinionated design skill does will recalibrate your sense of what is possible from a single skill file.

**Write your own DESIGN.md if you have a brand.** The `awesome-claude-design` pattern is: put your design system into a markdown file that any agent can read. Colors, typography, spacing, card patterns, don'ts. Keep it under 300 lines. Commit it to your repo root. Every agent session that touches UI will pull from it automatically.

If you need a concrete starting point, read [Design.md for AI Agents](/blog/design-md-for-ai-agents) for the repo-level pattern, then use [Create Beautiful UI with Claude Code](/blog/create-beautiful-ui-claude-code) as the implementation loop. For the skill layer specifically, [What Are Claude Code Skills?](/blog/what-are-claude-code-skills-beginner-guide) explains the beginner version and [why skills beat prompts](/blog/why-skills-beat-prompts-for-coding-agents-2026) explains the compounding workflow.

**Separate the design skill from the implementation skill.** The emerging pattern is one thread doing design exploration (high-variety, visual, opinionated) and a separate thread wiring the chosen design into actual code (low-variety, correct, constrained). Trying to do both in one agent turn produces diluted results in both directions.

## The bigger picture

The Claude Design moment is an instance of a larger trend: **skills are eating creative tools**. Last year, "AI for design" meant standalone apps (Midjourney, Runway, Figma AI). This year, it means a skill file in your repo that your existing agent loads on demand. No new app, no new subscription, no context switch.

If the pattern holds - and 8,000 stars in a week is a reasonable first indicator - the next few months will see the same shift in other domains. Research skills. Legal drafting skills. Financial modeling skills. Each one a single markdown file, each one loadable by any agent, each one replacing what used to be a separate product.

The developers shipping those skills are going to compound faster than the developers still shopping for tools. The whole [skills-marketplace thesis](https://skills.developersdigest.tech) is that the unit of AI leverage is shifting from "which product do I buy" to "which skill do I load." This week's Claude Design trend is the clearest single-week evidence of that shift that I have seen.

Worth watching. Worth trying one. Worth writing your own.

## Frequently Asked Questions

### What is Claude Design?

Claude Design refers to the emerging practice of using Claude Code skills to generate high-quality UI and visual assets. Rather than a single product, it describes a pattern: loading a specialized `SKILL.md` file that encodes design philosophies, then letting Claude Code generate HTML, CSS, animations, and prototypes that follow those rules. The repos trending this week - huashu-design, open-codesign, awesome-claude-design, cc-design - are all implementations of this pattern.

### How do I install a Claude Design skill?

Most Claude Design skills install with a single command. For example: `npx skills add alchaincyf/huashu-design`. This downloads the skill's `SKILL.md` file into your project so Claude Code reads it automatically when you ask for design work. Some skills like awesome-claude-design are reference lists rather than installable packages - you copy the `DESIGN.md` content you want directly into your repo.

### What is the difference between a SKILL.md and a DESIGN.md?

A `SKILL.md` is an instruction file that tells Claude Code how to perform a task - like designing UI, running code review, or generating tests. A `DESIGN.md` is a specification file that describes your design system - colors, typography, spacing, component patterns. They work together: the skill defines the workflow, the design file defines the visual rules. Both live in your repo and load automatically.

### Can I use Claude Design skills with other AI coding tools?

The `SKILL.md` format is Claude Code specific, but the underlying `DESIGN.md` pattern works with any AI coding tool that reads repo context. Cursor, Codex, and Windsurf can all read a `DESIGN.md` file if you reference it in your prompts or project instructions. The design specification itself is portable even if the skill wrapper is not.

### How do Claude Design skills prevent AI design slop?

AI design slop happens when agents default to generic, recognizable patterns - colored left borders, excessive gradients, emoji padding. Claude Design skills prevent this by loading opinionated defaults before generation starts. Huashu-design's twenty design philosophies, for example, explicitly encode what not to do. The constraint layer runs before the generation layer, which produces output that looks intentional rather than default.

### Are Claude Design skills free?

All four repos trending this week are public GitHub projects you can inspect and try. Open-codesign and awesome-claude-design currently advertise MIT licenses; huashu-design and cc-design should be checked repo-by-repo before commercial reuse because their licensing details are not equally standardized in GitHub metadata. Tooling costs also vary by workflow because some projects run as Claude Code skills, some are reference collections, and some support multiple agent surfaces.

### What is the best Claude Design skill for beginners?

Start with [awesome-claude-design](https://github.com/VoltAgent/awesome-claude-design) if you want inspiration - it is a curated list of 68 design system examples you can copy from. Start with [huashu-design](https://github.com/alchaincyf/huashu-design) if you want a fully opinionated system that generates complete designs from short prompts. The first is a reference, the second is a workflow.

### How do I write my own design skill?

Start by reading [Writing Your First Claude Code Skill](/guides/writing-your-first-claude-code-skill) for the general pattern. For design specifically, create a `DESIGN.md` in your repo root with your brand colors, typography, spacing grid, component patterns, and explicit don'ts. Keep it under 300 lines. Then create a `SKILL.md` that references the design file and describes the workflow Claude should follow when generating UI. The [Design.md for AI Agents](/blog/design-md-for-ai-agents) guide walks through the repo-level pattern in detail.

## Further reading

- [AI Design Slop: 15 Patterns That Out Your App as Vibe-Coded](/blog/ai-design-slop-and-how-to-spot-it) - the study that set the vocabulary
- [Writing Your First Claude Code Skill](/guides/writing-your-first-claude-code-skill) - build your own
- [Zed's Parallel Agents: The Editor Catches Up](/blog/zed-parallel-agents-first-editor-making-it-native) - per-thread specialized agents
- [Design.md for AI Agents](/blog/design-md-for-ai-agents) - turn design preferences into standing repo context
- [Create Beautiful UI with Claude Code](/blog/create-beautiful-ui-claude-code) - practical Claude Code design workflow


The Agent Reliability Cliff: Why Your 10-Step Chain Only Succeeds 20% of the Time
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT
## The math nobody wants to do

Your agent pipeline is a compound probability problem, and the compound destroys you faster than you think.

Assume a single agent step succeeds 85 percent of the time. That is a generous number. Real-world per-step reliability for non-trivial tasks is often closer to 80 percent. Now chain ten of those steps together. The end-to-end success rate is 0.85 to the tenth, which is roughly 20 percent.

That is the agent reliability cliff. Five steps holds up decently at 44 percent end-to-end. Ten steps collapses to 20 percent. Twenty steps is effectively zero. This is not a tooling problem or a model problem. It is the arithmetic.

Everyone who has shipped a multi-agent pipeline has hit this wall. You prototype a five-step flow and the demo video looks amazing. You add five more steps for the production edge cases and suddenly four out of five runs fail partway through. You blame the model, or the prompt, or [Anthropic](/blog/anthropic-vs-openai-developer-experience) having a bad day, and you cannot figure out why it worked yesterday and it does not work today. The answer is usually that it was never really working. Your demo was sampling the 20 percent of runs that happened to succeed end-to-end.

This post is a rough map of what the field has converged on to fight this. The patterns are not new, but they are finally common vocabulary in production agent work.

## Why 85 percent is optimistic

Per-step reliability is a moving target. Here is what affects it.

**Task complexity.** An agent that summarizes a paragraph succeeds above 95 percent. An agent that writes a bug fix to a real codebase succeeds in the 60-80 percent range depending on the specificity of the bug. An agent that has to decide whether to refactor or patch is rarely above 70 percent.

**Context pressure.** Agents that operate near their context window limit start truncating, hallucinating, and dropping instructions. A prompt that works at 10k tokens of context may fail at 100k tokens on the same task.

**Tool use surface area.** Every tool the agent can call is a place where the agent can call the wrong tool, pass the wrong arguments, or interpret the response incorrectly. More tools means more error modes.

**Environment variance.** The exact same prompt produces different outputs run to run. Temperature is usually non-zero. Even with temperature zero, provider-side fluctuations matter.

The practical implication: optimistic planners assume 90 percent per step and build 15-step pipelines. Realistic planners assume 80 percent per step and cap chains at five steps, with verification gates between them. The realistic planners are the ones whose agents ship.

## The six patterns that actually work

After two years of production agent work, six reliability patterns keep showing up. None of them are exotic. All of them are boring infrastructure-engineering instincts applied to agent pipelines.

### 1. Retry with backoff

The baseline. If a step fails, retry it. Exponential backoff between retries to avoid hammering a flaky upstream. Cap at three or four retries, then escalate.

Retry only works for transient failures. A hallucination in agent output is not a transient failure. It is often a deterministic failure that will reproduce on retry. So retry is necessary but insufficient.

### 2. Self-healing loops

The step produces output and also a verification pass. If verification fails, the step retries itself with the failure as context. This is the evaluator-optimizer loop in production.

The key is that the verification has to be executable. A test suite. A schema validator. A linter. A rubric evaluated by another LLM. If "verification" is the same LLM eye-balling its own output, you have not actually added verification. You have added self-congratulation.

This pattern works extraordinarily well for code generation. Generate, run the tests, loop if they fail, cap at three iterations. Empirically, a single retry on a test failure captures 60-70 percent of the cases where the first attempt was wrong.

### 3. Circuit breaker

Underused. If the error rate from a specific sub-agent exceeds a threshold over a rolling window, stop routing work to it and alert. Prevents cascade failures where one broken agent drags the whole system down.

Circuit breakers are the pattern that lets you run the pipeline overnight without waking up to a $400 API bill from an infinite retry loop.

### 4. Checkpoint and resume

Long-running agent work should save state after every major step. When a failure happens in step seven, you resume from the checkpoint before step seven, not from step one.

The state has to be external. Postgres, Redis, Convex, a flat JSON file. Anything but "in the agent's memory" because the agent's memory is what just failed.

Checkpointing changes the math. A 10-step chain with checkpoints and per-step retry is functionally a 10 x 2-step chain, which at 85 percent reliability is 72 percent end-to-end. Ten times more reliable than the same chain without checkpoints.

### 5. Early stopping

Sometimes the right move is to stop and escalate rather than retry. If the agent has tried three approaches and all failed, the fourth will probably fail too. Stop. Surface the failure to a human or a different specialist agent.

Early stopping is a cost control as much as a reliability control. The failure mode without early stopping is $50 of tokens burned on an agent stuck in a confusion loop.

### 6. Human escalation

The best agents know when to ask. The worst agents never ask. Every production pipeline needs a clear definition of the conditions under which the agent stops and requests human input rather than continuing to guess.

Common escalation triggers: the agent has made the same kind of mistake twice. The agent's confidence (if you can measure it) drops below a threshold. The next action crosses a blast-radius line the agent is not authorized to cross alone.

## State management, briefly

The reliability patterns above assume agents are stateless and state lives somewhere durable. This is the production winner and the debate is mostly over.

Agents load their state at the start of a run and save it at the end. Benefits: resumability, full auditability, parallel execution without race conditions, the ability to run the same agent on the same state from two different machines without corruption.

Message queue architectures (Redis Pub/Sub, SQS, Kafka) decouple agents for high-volume workloads. They are overkill for most agent pipelines, but if your workload spikes or needs durable semantics, Temporal or Inngest are the two orchestrators most agent teams pick.

## Cost as the other side of reliability

Cost optimization and reliability are tied. A pipeline that [costs](/blog/ai-coding-tools-pricing-comparison) $0.10 per run can tolerate 20 percent success rates if retries are free. A pipeline that costs $5 per run cannot.

The three cost levers that matter in production:

**Model tier routing.** Use the cheapest model that can handle each sub-task. Tiny models for routing and classification. Medium models for worker tasks. Large models only for planning and synthesis. A Claude Opus orchestrator with Haiku workers can cut costs by an order of magnitude versus using Opus throughout, with minimal quality loss on the worker side.

**Prompt caching.** Anthropic and OpenAI both support [prompt caching](/blog/prompt-caching-claude-api-production-guide). System prompts and tool definitions repeated across thousands of agent calls should hit 70 percent-plus cache rates. At current pricing that is a 60-90 percent cost reduction on cached tokens. If you are not using prompt caching in production, you are leaving money on the table.

**Batch API.** Both Anthropic and [OpenAI](/blog/openai-vs-anthropic-2026) offer 50 percent discounts for async batch jobs with 24-hour windows. Most agent pipelines have at least some batchable work: nightly report generation, bulk document analysis, overnight data enrichment. Run the non-urgent parts of your pipeline through the batch API and cut that cost line in half.

## The practical shape

Put the whole picture together and a reliable production agent pipeline looks like this.

Five steps or fewer in any single chain. Each step has executable verification. Each step is checkpointed to durable state. Retries are bounded with exponential backoff. Circuit breakers guard expensive sub-agents. Unrecoverable failures escalate to a human via a defined trigger. The cheapest sufficient model runs each step. Prompt caching hits 70 percent-plus. Batch API absorbs anything that does not need to run now.

That is not exciting. It is plumbing. But it is plumbing that ships, and plumbing that does not ship is why 80 percent of demo agent pipelines never make it to production.

## Where this goes next

The field is converging on two answers to the reliability cliff.

The first is "smaller, better-scoped steps." If you cannot make a single step 95 percent reliable, break it into two steps that are each 97 percent reliable and run them with verification between.

The second is "specialized sub-models fine-tuned for narrow tasks." A sub-model trained specifically to produce JSON that passes a schema check is more reliable than a general model asked to produce JSON and hope. This is where agent-specialized fine-tuning is headed over the next eighteen months.

In the meantime, the boring answer is the right answer. Shorter chains. Executable verification. Durable state. Bounded retries. Circuit breakers. Escalation paths. Cheapest sufficient model. Caching. Batching.

Agent reliability is an infrastructure problem. Most of what looks like AI is just good plumbing.

## FAQ

### What is the agent reliability cliff?

The agent reliability cliff describes how per-step success rates compound exponentially across multi-step agent pipelines. If each step succeeds 85% of the time, a 10-step chain only succeeds about 20% end-to-end (0.85^10). The math is brutal: 5 steps holds at 44% success, 10 steps drops to 20%, and 20 steps is effectively zero. Most failed agent projects hit this wall without understanding the compound probability math.

### Why do my agent demos work but production fails?

Demo videos sample the runs that happened to succeed. A 10-step pipeline with 20% end-to-end success means four out of five runs fail partway through. In a demo, you re-record until you get a good run. In production, users see every failure. The pipeline was never really working - the demo was just statistical cherry-picking.

### How do I improve agent pipeline reliability in production?

The six patterns that work: (1) Retry with exponential backoff for transient failures, (2) Self-healing loops with executable verification (tests, schema validators, linters), (3) Circuit breakers to stop cascade failures, (4) Checkpoint and resume to avoid restarting from scratch, (5) Early stopping after repeated failures, and (6) Human escalation when the agent should ask rather than guess. None are exotic - they are boring infrastructure engineering applied to agent pipelines.

### What is executable verification for agents?

Verification that runs code, not vibes. A test suite that passes or fails. A JSON schema validator. A linter. A rubric evaluated by a separate LLM. If verification is the same LLM reviewing its own output, that is not verification - it is self-congratulation. Executable verification is what makes self-healing loops actually heal.

### How do circuit breakers help agent reliability?

Circuit breakers stop routing work to a sub-agent when its error rate exceeds a threshold over a rolling window. They prevent cascade failures where one broken agent drags the whole system down. More importantly, they prevent the $400 overnight API bill from an infinite retry loop. If you run agent pipelines unattended, circuit breakers are mandatory.

### How does checkpointing improve agent pipeline success rates?

Checkpointing changes the math. A 10-step chain with checkpoints and per-step retry is functionally a series of 2-step chains (step + retry). At 85% reliability, that is 72% end-to-end instead of 20%. The key: state must be external (Postgres, Redis, Convex, flat file), not in the agent's memory, because the agent's memory is what just failed.

### What is the optimal number of steps in an agent chain?

Realistic planners cap chains at 5 steps with verification gates between them. At 80% per-step reliability, 5 steps gives 33% end-to-end success. 10 steps gives 11%. Optimistic planners assume 90% and build 15-step pipelines that never ship. If you need more than 5 steps, add checkpoints and treat it as multiple 5-step chains with durable state handoffs.

### How do I reduce AI agent pipeline costs while maintaining reliability?

Three levers: (1) Model tier routing - use tiny models for classification, medium models for workers, and large models only for planning. Claude Opus orchestrator + Haiku workers cuts costs 10x. (2) Prompt caching - system prompts and tool definitions should hit 70%+ cache rates for 60-90% cost reduction. (3) Batch API - 50% discount for async jobs. Cost and reliability are tied: a $0.10 pipeline can tolerate 20% success; a $5 pipeline cannot.

## Further reading

- [7 AI Agent Orchestration Patterns Every Developer Should Know](/blog/seven-ai-agent-orchestration-patterns)
- [Over-Editing: Why Your AI Agent Rewrites What Isn't Broken](/blog/over-editing-when-ai-rewrites-what-isnt-broken)
- [Building Multi-Agent Workflows with Claude Code](/blog/building-multi-agent-workflows-claude-code)


Terminal CLI - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The terminal CLI is the main way to run Claude Code. You install it once, then start a session with a single command in any project directory.

## What it does

The `claude` command launches an interactive session wired to your repo. It reads `CLAUDE.md`, loads your skills and MCP servers, respects permission settings, and runs tools like Read, Edit, and Bash. Output streams to your terminal in real time, and you can swap models or modes mid-session without restarting.

## When to use it

- You want the fastest path into Claude Code on a new project.
- You prefer a terminal-first workflow over an IDE extension.
- You need full access to tools, hooks, skills, and MCP without UI overhead.
- You're scripting and want the same binary that powers every other surface.

## Gotchas

- First run prompts for auth. Don't commit the token that gets cached in `~/.claude/`.
- Running `claude` outside a git repo still works but skips repo-aware features like worktrees and PR status.
- If you launch inside a tmux or screen session, set your terminal type correctly or keybindings may misbehave.

Official docs: https://code.claude.com/docs/en/quickstart.md


Interactive Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Interactive mode is the default Claude Code experience - a persistent prompt where you type, Claude runs tools, and you iterate turn by turn.

## What it does

The interactive loop handles input, tool calls, and streaming output in one session. It supports command history, multiline prompts, tab completion, and inline UI for permission dialogs. You can switch models, toggle plan mode, open the transcript viewer, or drop to a bash shell without leaving the loop.

## When to use it

- Most day-to-day coding work where you want to review each step.
- Long debugging sessions where conversation state matters.
- Exploring a new codebase with back-and-forth refinement.
- Any task where headless mode would be overkill.

## Gotchas

- The prompt buffer is per-session - moving between projects loses the last draft unless you use command history.
- Multiline paste behavior depends on your terminal; if newlines get flattened, enable bracketed paste.
- Some shortcuts collide with terminal multiplexer bindings. Check your tmux config if Ctrl+B conflicts.

Official docs: https://code.claude.com/docs/en/interactive-mode.md


Keyboard Shortcuts - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code ships with 50+ keyboard shortcuts covering session control, history navigation, transcript viewing, and prompt editing.

## What it does

Default bindings include Ctrl+C to cancel the current turn, Ctrl+R for reverse history search, Ctrl+O for the transcript viewer, and Alt+T to toggle extended thinking. You can remap any of them by editing `~/.claude/keybindings.json`. Bindings respect modifier combinations and chord sequences.

## When to use it

- You want to move faster in long sessions without reaching for the mouse.
- Your muscle memory from vim, emacs, or readline needs specific keys.
- You have conflicts with your terminal multiplexer or IDE bindings.
- You run Claude Code across machines and want a portable keymap.

## Gotchas

- Some shortcuts won't fire inside tmux unless you pass through the prefix key.
- Remote sessions over SSH can swallow Alt-based chords. Use Escape-prefix alternatives.
- Vim mode overrides several defaults while in normal mode - see the vim mode guide for the full map.

Official docs: https://code.claude.com/docs/en/keybindings.md


Vim Editor Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Vim editor mode turns the Claude Code prompt into a modal editor with familiar normal and insert mode bindings.

## What it does

Enable vim mode and your prompt supports `h j k l` motion, `w b e` word jumps, `dd` line delete, `yy` yank, `p` paste, and insert mode via `i`, `a`, or `o`. Escape returns to normal mode. It works on single-line and multiline drafts alike, so you can compose long prompts the same way you'd compose code.

## When to use it

- You already live in vim or neovim and want consistent motions.
- You draft long, complex prompts that benefit from modal editing.
- You find yourself reaching for arrow keys too often.
- You want `.` repeats and `u` undo in the prompt buffer.

## Gotchas

- Some readline shortcuts are disabled while vim mode is active. Check the keybindings doc for the full swap.
- Visual mode selections don't integrate with system clipboard on every terminal.
- If you toggle vim mode mid-session, the current draft keeps its previous mode behavior until you press a motion.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#vim-editor-mode


Background Tasks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Background tasks let long-running shell commands run alongside your session without blocking the prompt.

## What it does

Press Ctrl+B or pass the background flag to a Bash tool call, and Claude starts the command asynchronously. You get a task ID back immediately. Claude can poll the task's stdout and stderr later, stream new output into context, or stop it via TaskStop. This is how dev servers, test watchers, and long builds stay alive across turns.

## When to use it

- Running `npm run dev`, `pnpm test --watch`, or similar long processes.
- Kicking off a build while Claude keeps coding.
- Tailing logs or monitoring a process without blocking your chat.
- CI-style jobs where you want Claude to check back periodically.

## Gotchas

- Background tasks don't persist across sessions. Restart claims a fresh process.
- Output buffers have limits - very chatty processes may get truncated. Pipe to a file for full logs.
- Forgetting to stop a background task leaves orphaned processes. Always call TaskStop or close the session cleanly.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#background-bash-commands


Bash Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Bash mode lets you drop straight into the shell without spending a turn asking Claude to run a command.

## What it does

Start any prompt with `!` and the rest of the line runs as a shell command. Output appears inline and is captured into the conversation so Claude can reference it on the next turn. This is faster than `please run ls -la` and more honest - you're not spending tokens on the interpreter round-trip.

## When to use it

- Quick directory listings, git status checks, or file inspections.
- Sanity-checking the shell state before asking Claude to do real work.
- Piping output into a follow-up Claude prompt without editing files.
- Teaching Claude about your environment without explaining it.

## Gotchas

- Bash mode respects your current permission rules. Denied commands still get blocked.
- The working directory is the same as Claude's Bash tool, not wherever your outer terminal sits.
- Shell state (exported vars, aliases) doesn't persist between bash-mode calls unless you use SessionStart hooks.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#bash-mode-with--prefix


Command History - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code keeps a per-directory history of the prompts you've typed, searchable the same way your shell history is.

## What it does

Every prompt you submit gets stored, scoped to the project directory. Up and down arrows cycle through entries. Ctrl+R opens reverse search - type a fragment and Claude jumps to the most recent match. History survives restarts, so repeated prompts like "run the tests" are one keystroke away.

## When to use it

- Re-running common prompts without retyping them.
- Grabbing a complex prompt you wrote yesterday and tweaking it.
- Building a mental library of what works in a given repo.
- Quickly returning to a prompt after a failed attempt.

## Gotchas

- History is per-directory. Switching projects starts fresh.
- There's no built-in secret redaction - if you paste an API key into a prompt, it sits in history. Clear it manually.
- Very long prompts still take a single slot. Reverse search only matches the first line well.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#command-history


Voice Dictation - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Voice dictation lets you speak your prompt instead of typing. Hold a key, talk, release, and the transcription fills the prompt buffer.

## What it does

Claude Code records audio while you hold the dictation key, transcribes it locally or via Anthropic's speech service depending on config, and inserts the text at your cursor. You can pick a language, pick a model, and edit the result before submitting. It works on macOS, Linux, and Windows.

## When to use it

- Long, ranty prompts that are faster to say than type.
- Accessibility workflows where typing is tiring or not possible.
- Brainstorming out loud while Claude captures the intent.
- Mobile-adjacent setups where you're away from a full keyboard.

## Gotchas

- Microphone permission has to be granted to your terminal emulator. Some terminals need a restart after the grant.
- Background noise matters. Transcription quality drops fast in a noisy room.
- The transcript lands as plain text - double-check code snippets or file paths before submitting.

Official docs: https://code.claude.com/docs/en/voice-dictation.md


Multiline Input - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Multiline input lets you compose long prompts without hitting submit on every line break.

## What it does

Shift+Enter, Option+Enter, or a trailing backslash followed by Enter all insert a newline into the prompt buffer instead of sending it. You can paste multi-line code blocks, write step-by-step instructions, or draft a structured prompt in place. Regular Enter still submits when you're ready.

## When to use it

- Pasting code samples, logs, or error messages into a prompt.
- Writing a structured brief with sections and bullets.
- Composing a prompt that mixes prose with file paths or commands.
- Any time your prompt is longer than one terminal line.

## Gotchas

- Some terminals don't distinguish Shift+Enter from Enter. Use backslash + Enter as a universal fallback.
- Bracketed paste mode affects how multi-line pastes are interpreted - enable it in your terminal config.
- Vim mode has its own multiline behavior. Use `o` from normal mode to open a new line cleanly.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#multiline-input


Prompt Suggestions - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Prompt suggestions surface likely next prompts based on your repo's git history and recent work.

## What it does

When Claude finishes a turn, it may show a short list of suggested follow-ups - things like "write tests for this", "open a PR", or "revert the last change" - informed by your commit log, staged changes, and current branch. Press a number or arrow key to select one instead of typing it yourself.

## When to use it

- You want a nudge toward natural next steps without thinking hard.
- Onboarding to a new repo where you're not sure what's idiomatic.
- Batch sessions where you want to pattern-match on common workflows.
- Keeping momentum through a long debugging or refactoring session.

## Gotchas

- Suggestions are best-effort. They can be off-base in unusual repos or fresh clones with no history.
- Accepting a suggestion still runs a full turn - it's not free. Treat them like prompt starters.
- They won't surface when your git state is ambiguous (detached HEAD, empty repo).

Official docs: https://code.claude.com/docs/en/interactive-mode.md#prompt-suggestions


Side Questions with /btw - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The `/btw` command (short for "by the way") lets you ask a tangential question without losing the thread of your main task.

## What it does

When you type `/btw `, Claude answers in a lightweight context that doesn't add to the current task's working memory. It's useful for quick clarifications - "what does this flag do?" or "is there a shorter way to write this?" - without polluting the primary conversation.

## When to use it

- You're deep in a task and need a one-off fact before continuing.
- You want to sanity-check something without spending tokens on tool calls.
- You have a follow-up idea but don't want to start a new session.
- You're onboarding and frequently need meta-context.

## Gotchas

- Side questions still count against your overall quota and context budget, just more cheaply.
- Don't use `/btw` for anything that needs tool access - it's meant for chat, not editing.
- Nested `/btw` calls aren't supported. One side question at a time.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#side-questions-with-btw


Read Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The Read tool is how Claude pulls file contents into context - the foundation of nearly every real coding task.

## What it does

Read takes an absolute path and returns the file contents with line numbers prefixed. It supports offset and limit arguments so Claude can page through huge files without loading them entirely. It also handles images, PDFs, and Jupyter notebooks, returning appropriate representations for each.

## When to use it

- Any task where Claude needs to understand existing code.
- Reviewing config files, logs, or test output.
- Grabbing a specific line range from a large file.
- Loading an image or PDF for analysis.

## Gotchas

- Empty files return a warning instead of content. Don't panic if you see it.
- Line-numbered output is for reading only - never paste those line numbers into Edit.
- Very large PDFs need a pages parameter. Unbounded PDF reads fail.

Official docs: https://code.claude.com/docs/en/tools-reference.md


Write Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The Write tool creates new files or replaces existing ones entirely. It's the simplest way to put content on disk.

## What it does

Write takes an absolute path and a body of content and writes it atomically. Overwriting an existing file requires that Claude has Read it in the current session, which prevents accidental clobbering. For partial edits, the Edit tool is almost always the right choice instead.

## When to use it

- Creating a brand-new file from scratch.
- Complete rewrites where an Edit would be longer than the new content.
- Generating boilerplate like config files, templates, or scaffolds.
- Writing binary content through base64 round-trips is not supported - use Bash for that.

## Gotchas

- Write overwrites without merging. A typo in the path can destroy a file.
- You cannot Write to a path you haven't Read unless it's new. This is a safety feature.
- Prefer Edit over Write for existing files - diffs are cheaper to review.

Official docs: https://code.claude.com/docs/en/tools-reference.md


Edit Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Edit is the workhorse for modifying existing files. It performs exact string replacements so you review a diff, not a whole new file.

## What it does

Edit takes a file path, an old string, and a new string. It replaces the first occurrence - or all occurrences with `replace_all` - and leaves everything else untouched. Because it's a diff-style edit, the change is easy to review and less likely to introduce regressions than a full-file Write.

## When to use it

- Fixing bugs in specific lines or blocks.
- Renaming variables or functions across a file with `replace_all`.
- Tweaking config values without rewriting config.
- Any change where the rest of the file should stay byte-identical.

## Gotchas

- The `old_string` must be unique in the file unless you use `replace_all`. Include surrounding context to make it unique.
- Indentation must match exactly - tabs versus spaces will break a match.
- Edit requires a prior Read of the file. Claude won't edit sight unseen.

Official docs: https://code.claude.com/docs/en/tools-reference.md


MultiEdit - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MultiEdit applies a set of edits to one or many files in a single tool call. It's the fastest way to make coordinated changes.

## What it does

You pass MultiEdit a list of file + old_string + new_string triples. It applies them in order, either all succeeding or the whole batch rolling back. This is ideal for refactors that touch several files at once - renaming an export, updating an API signature, shifting a config key across consumers.

## When to use it

- Refactors that span multiple files and must stay consistent.
- Coordinated edits where a partial failure would leave the repo broken.
- Repetitive changes you'd otherwise do with ten sequential Edit calls.
- Reducing turn count in long sessions.

## Gotchas

- A single failed edit rolls back the whole batch. Order matters.
- Each edit still has the unique-old-string requirement. A typo in one triple blocks everything.
- Large batches are harder to review. Keep them focused on one logical change.

Official docs: https://code.claude.com/docs/en/tools-reference.md


Notebook Edit - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Notebook Edit lets Claude modify `.ipynb` files as cells, not as raw JSON. It understands the notebook format so edits don't corrupt the file.

## What it does

The tool targets a specific cell by ID or index, replaces its source, or inserts a new cell. It preserves outputs, metadata, and cell types (code, markdown, raw) unless you explicitly overwrite them. This is how Claude works in data science projects without breaking the notebook on save.

## When to use it

- Editing existing `.ipynb` files in data science, ML, or analysis repos.
- Adding a new cell to an exploratory notebook.
- Cleaning up a notebook before committing.
- Any task where hand-editing JSON would be error-prone.

## Gotchas

- Cell IDs are the most stable reference. Index-based edits break if cells are reordered.
- Outputs don't get cleared automatically - use a separate step if you want a clean notebook.
- Large output blobs stay in context when Claude reads the notebook. Clear outputs first for cheaper reads.

Official docs: https://code.claude.com/docs/en/tools-reference.md


Glob Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Glob finds files by path pattern. It's the fastest way to answer "where are all the X files?" in a repo.

## What it does

Glob accepts shell-style patterns like `**/*.ts` or `src/components/*.tsx` and returns matching paths. It's fast, respects `.gitignore`, and works well as a pre-step before a Grep or a batch of Reads. You can scope it to a subdirectory to narrow the search.

## When to use it

- Locating all files of a type (`**/*.md`, `**/*.yaml`).
- Finding the right entry point before reading.
- Generating a worklist for a large refactor.
- Confirming a file was actually written.

## Gotchas

- Glob does not search file contents - use Grep for that.
- Patterns are case-sensitive on most filesystems.
- Hidden files (`.env`, dotfiles) need an explicit pattern like `.*` or `**/.*`.

Official docs: https://code.claude.com/docs/en/tools-reference.md


Grep Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Grep searches the contents of files in the repo. It's how Claude finds usages, references, and matching lines without reading every file.

## What it does

Grep runs a regex (or plain string) against file bodies and returns matching lines with file paths. You can scope it to a subdirectory, filter by glob, and ask for counts or file-only output. It's powered by a fast recursive search so it handles large repos comfortably.

## When to use it

- Finding usages of a function, component, or constant.
- Hunting down TODO comments or error strings.
- Pre-filtering files before a multi-file edit.
- Confirming that a symbol doesn't leak beyond expected modules.

## Gotchas

- Regex special characters need escaping - parens, brackets, pipes, dots.
- Grep returns bounded output. Very noisy patterns get truncated - narrow the scope.
- Results respect `.gitignore` by default, so node_modules stays out of the way.

Official docs: https://code.claude.com/docs/en/tools-reference.md


LSP Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The LSP tool wires Claude into the same Language Server Protocol your IDE uses. That means real "jump to definition" and "find references", not regex guesses.

## What it does

Claude Code talks to your project's installed language servers to resolve symbols, find references, pull type info, and report diagnostics. When you ask "where is this function used?", the LSP returns real call sites from the compiler, not a Grep that might catch comments or strings.

## When to use it

- Any task involving TypeScript, Python, Rust, Go, or other LSP-supported languages.
- Refactors where you need to hit every real reference.
- Investigating type errors or diagnostics.
- Understanding unfamiliar code with precise navigation.

## Gotchas

- The language server has to be installed and runnable in your environment.
- First-run indexing can be slow on large monorepos. Subsequent queries are fast.
- Some languages have thin LSP support - fall back to Grep if definitions come back empty.

Official docs: https://code.claude.com/docs/en/tools-reference.md#lsp-tool-behavior


Bash Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The Bash tool runs shell commands. It's the most capable and most-permissioned tool in Claude Code, which is why every session has at least one rule about it.

## What it does

Bash runs a command in a persistent shell whose working directory sticks within the project. Output comes back as combined stdout+stderr, truncated if huge. You can run it in the background for long processes, pipe, use heredocs, and chain commands. Permission rules gate which commands are allowed.

## When to use it

- Running tests, builds, linters, and formatters.
- Git operations, file system changes, and installs.
- Anything that's faster as a one-liner than a tool sequence.
- Invoking project-specific CLIs.

## Gotchas

- Interactive prompts hang the tool. Pass flags or pipe input instead of waiting for TTY.
- Shell state (exported vars, `cd` in subshells) doesn't persist beyond a single call unless you chain with `&&`.
- Newlines are blocked in command strings on some setups. Use quoted strings or here-docs for multi-line payloads.

Official docs: https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior


PowerShell Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PowerShell Tool gives Claude first-class shell access on Windows without fighting cmd.exe or relying on WSL.

## What it does

The tool runs PowerShell commands - cmdlets, scripts, pipelines - inside the session's working directory. It's the preferred shell on Windows and is available opt-in on macOS and Linux if you have PowerShell Core installed. Output is captured the same way the Bash tool handles it.

## When to use it

- Windows-first development where PowerShell is native.
- Tasks involving .NET, Azure CLI, or other PowerShell-friendly tooling.
- Cross-platform scripts written in PowerShell.
- Avoiding POSIX-ism mismatches when Claude tries Unix-style commands on Windows.

## Gotchas

- PowerShell Tool is preview on Windows - expect rough edges on obscure cmdlets.
- Execution policy may block scripts. Set it explicitly in your session if needed.
- Pipeline output differs from Bash - objects versus text - so don't assume awk/sed-style post-processing works.

Official docs: https://code.claude.com/docs/en/tools-reference.md#powershell-tool


Monitor Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Monitor watches a process, file, or log stream in the background and pushes new output into the conversation as it arrives.

## What it does

You hand Monitor a command or a file path and it keeps streaming. Each line of output becomes a notification Claude can react to. It's designed for the "until this condition is true" pattern - tail a deploy log until you see "ready", watch a test file for a green run, or poll a dev server's health endpoint.

## When to use it

- Waiting on a deploy or CI job without wasting a `sleep` loop.
- Tailing a log for a specific event.
- Keeping eyes on a dev server while Claude works on other code.
- Long-running background work where polling would be wasteful.

## Gotchas

- Monitor is in preview. Behavior may change between Claude Code releases.
- Very chatty output floods the conversation quickly. Filter at the source.
- Always stop the monitor when you're done or it burns context for nothing.

Official docs: https://code.claude.com/docs/en/tools-reference.md#monitor-tool


Environment Variable Persistence - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Environment variable persistence lets you set values once at session start and have them survive every subsequent Bash tool call.

## What it does

Normally each Bash tool call gets a fresh shell - `export FOO=bar` in one call is gone in the next. A SessionStart hook can set env vars that Claude Code injects into every Bash invocation, so secrets from a vault, feature flags, or project-specific paths are always available. This is the clean alternative to hardcoding values in prompts.

## When to use it

- Injecting API keys from a secret manager into every tool call.
- Pointing Claude at a specific Node, Python, or Ruby version.
- Setting project-specific env vars without committing them.
- Toggling debug flags for a whole session.

## Gotchas

- The hook runs once per session. If the value changes mid-session, you have to restart.
- Large env payloads slow down every Bash call. Keep them lean.
- Hooks run in your environment with your permissions - treat them like any other secret-touching script.

Official docs: https://code.claude.com/docs/en/tools-reference.md#bash-tool-behavior


Git Integration - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code treats git as a first-class tool. Commits, branches, and PRs happen through the same Bash tool you'd use manually, but Claude knows the common patterns.

## What it does

Claude can run `git status`, `git diff`, `git log`, stage specific files, write a commit message, and push. With `gh` installed, it can also open PRs and read review state. The workflow mirrors a careful human - check status, review the diff, craft a message, commit. It won't push or merge unless you explicitly ask.

## When to use it

- Committing work after each meaningful change.
- Writing commit messages that match repo style.
- Creating feature branches for experiments.
- Opening PRs with a summary Claude generated from the diff.

## Gotchas

- Claude won't force-push, rebase destructively, or skip hooks unless you tell it to.
- By default, Claude only commits when you ask - it's not proactive about it.
- Sensitive files (`.env`, credentials) should stay in `.gitignore`. Claude respects ignores but a stray `git add -A` is still worth catching.

Official docs: https://code.claude.com/docs/en/quickstart.md


Worktrees - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Git worktrees let you run multiple Claude Code sessions against the same repo on different branches without stomping on each other.

## What it does

A worktree is a second checkout of the same repo, pointing at a different branch. Claude Code's `EnterWorktree` tool creates one, runs tasks in it, and exits back to the main checkout when done. Each session has its own working directory, its own branch, and its own in-flight changes - but shares the git object store.

## When to use it

- Running two or three agents in parallel on different features.
- Keeping a clean main checkout while Claude experiments in a branch.
- Reviewing a PR in isolation without stashing.
- Dogfooding branch-heavy workflows like stacked PRs.

## Gotchas

- Some tools (node_modules, build artifacts) need a separate install in each worktree.
- Hooks that assume a single working directory may misfire. Check your SessionStart scripts.
- Cleaning up abandoned worktrees takes an explicit prune - they're not garbage-collected.

Official docs: https://code.claude.com/docs/en/common-workflows.md#run-parallel-claude-code-sessions-with-git-worktrees


Writing Your First Claude Code Skill
Thu, 23 Apr 2026 00:00:00 GMT

## What a skill actually is

A Claude Code skill is a single markdown file that teaches Claude how to do one specific task the way you want it done. It lives at `~/.claude/skills//SKILL.md` and Claude auto-loads it when the trigger matches the current request.

Think of it as a playbook you hand to a good engineer who is about to start the task. The engineer is smart, so you do not need to teach them how to write code. You do need to tell them the shape of the task, the constraints that apply, the gotchas you have already discovered, and what "done" looks like. That is the skill.

By the end of this guide you will have written your first skill, installed it, triggered it from a real prompt, and understood the design decisions that make the difference between a skill that Claude actually uses and one that sits forgotten.

## The four parts of every skill

Every skill is a markdown file with YAML frontmatter. Four things matter:

1. **Name** - what the skill is called
2. **Description** - when Claude should trigger it
3. **Allowed tools** - which tools the skill expects Claude to have access to
4. **Body** - the actual instructions for doing the task

The frontmatter controls when the skill fires. The body controls what happens when it does. Getting both right is the whole craft.

## Pick a task worth turning into a skill

The first question is which tasks deserve a skill. The criteria:

- **You do it more than once.** A skill is a tax on every session's context load. Writing one for a task you do annually is not worth it. A task you do weekly absolutely is.
- **It has a consistent shape.** Skills encode patterns. If every instance of the task is wildly different, there is no pattern to encode.
- **You have an opinion about how it should be done.** Without an opinion, the skill is just a nudge toward "do a good job," which is not a skill. With an opinion, the skill becomes a style enforcer.
- **It has failure modes you want to prevent.** Skills are where you capture the lessons learned from mistakes. If a task has surprised you in the past, write the skill so future-you does not step in the same hole.

A bad first skill: "write code." Too vague. No opinion. No failure modes.

A good first skill: "add a new HTTP route to our Express API." Specific shape, conventions worth encoding (route handler file, input validation, error pattern, test file), known failure modes.

## Write the frontmatter

Let's walk through a concrete skill. Task: adding a new blog post to a Next.js content-markdown repo.

```yaml
---
name: add-blog-post
description: |
  Trigger when the user asks to add a blog post, write a new article, or
  publish a piece of content. Phrases: "add blog post", "write article",
  "new post", "publish", "add to blog".
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
---
```

The `description` is the most important field. It is what Claude reads when deciding whether to load your skill. Lead with the trigger condition ("Trigger when..."). Follow with example phrases.

The common mistake is writing a description that sounds like marketing copy. Skills do not need to sell themselves. They need to be findable by pattern matching. The phrases in the description are literal matches Claude uses to route the request to your skill.

`allowed-tools` is the declaration of what tools the skill expects to use. It is not a permission system, it is documentation. The skill author is telling the user "if your Claude Code config does not allow these, this skill will not work."

## Write the body

The body is a second-person playbook. You are writing instructions to another engineer.

Start with prerequisites. What has to be true before the skill can run? For the blog post example:

```markdown
## Prerequisites

- Markdown content directory identified (e.g., `content/blog/`)
- Frontmatter shape known (check an existing post for reference)
- Hero image directory identified if the site uses featured images
```

Continue with steps. Use numbered, imperative instructions. Each step should be one action the agent can verify.

```markdown
## Steps

1. **Find the content directory.** Glob `content/**/blog*` or check an
   existing post. Confirm with the user if there are multiple candidates.

2. **Read an existing post.** Pick the most recent post and study its
   frontmatter shape. Blog schemas vary: date format, tags array,
   relatedPosts, series fields. Do not guess.

3. **Create the new post file.** Use the slug as the filename:
   `content/blog/.md`. Never overwrite an existing file.

4. **Write the frontmatter.** Copy the shape from step 2. Fields that
   always matter:
   - title (sentence case, under 70 chars)
   - slug (kebab-case, matches filename)
   - excerpt (one sentence, not a rewrite of the title)
   - date (ISO)
   - tags (array, match existing site conventions)

5. **Write the body.** Open with a lead paragraph, not a heading.
   Use `## H2` for sections, not `#`. Short paragraphs. No em dashes.

6. **Verify frontmatter parses.** Run the site's build or lint step
   if available. If not, grep for any broken frontmatter on existing
   posts and match that pattern exactly.

7. **Tell the user what was added** and where. Include the slug and
   the file path.
```

The pattern: prerequisites, numbered steps, each step both specific and verifiable. No fluff.

## Write the failure-mode section

Every skill that ships should have a "common mistakes" or "anti-patterns" section. This is where you bake in the lessons from past failures.

```markdown
## Common mistakes to avoid

- Do not use em dashes. Use regular dashes with spaces.
- Do not guess at frontmatter fields. Read an existing post.
- Do not write a post without a date field. Sort order depends on it.
- Do not overwrite existing posts. If the slug collides, pick a new slug.
```

This is the highest-leverage section of the skill. Every item here is a mistake you, or Claude, or a prior session made before. Future sessions save the time of discovering it again.

## Write the output section

End the skill with a specification of what success looks like.

```markdown
## Output

- New markdown file at `content/blog/.md`
- Frontmatter matches existing post shape
- File passes the site's build or frontmatter validator
- User receives the slug and file path in the response
```

This section is both a contract for Claude and a checklist for you when reviewing the skill's output.

## Install the skill

Save the file as `~/.claude/skills/add-blog-post/SKILL.md`. Claude Code auto-discovers skills under `~/.claude/skills/*/SKILL.md` at session start.

To test it, start a new Claude Code session (or `/reload` in an existing one) and send a prompt that matches the description:

> "Add a blog post about our Q2 release"

Claude should load the skill, confirm the prerequisites, and follow the steps. If it does not load the skill, the description's trigger phrases probably did not match. Revise the description and retry.

## Test with real prompts

Test a skill with at least three prompts before trusting it:

1. The exact phrase from the description ("add a blog post")
2. A paraphrase the user might actually say ("can you write a new post about X")
3. An edge case (vague or partial request, e.g. "post about the new feature")

For each prompt, check that the skill loads, that Claude follows the steps in order, and that the output matches the spec. If any of these fail, the skill is not ready.

## Iterate from failure

The first version of any skill is wrong. You will see Claude skip a step, misinterpret a prerequisite, or invent a variation of the pattern. That is fine. The skill file is a living document. Every failure is a note to add to the "common mistakes" section or a clarification to add to the relevant step.

The most valuable skills in my library are on their fifth or sixth revision. Each revision captures a specific failure mode from real use.

## Keep the skill short

Skills that exceed 500 lines are usually too long. They are trying to teach Claude too many things at once and the trigger becomes muddy. When a skill grows past that threshold, split it.

A useful heuristic: if you could not verbally explain the skill to a new engineer in three minutes, it is too big.

## The six-line litmus test

Before you ship a skill, read the frontmatter and the first line of the body. If those seven lines answer "when should I use this?" and "what will happen if I do?", ship it. If they do not, rewrite before shipping. The most common skill failure is not that the body is bad but that the top of the file is vague.

## Where to go next

- Browse real SKILL.md examples at [skills.developersdigest.tech](https://skills.developersdigest.tech) for patterns across categories.
- Read our [context engineering guide](/blog/context-engineering-guide) for the broader theory behind skills, CLAUDE.md, and memory.
- Write a second skill. The gap between zero skills and one is large; the gap between one and three is smaller. Fluency comes with volume.

The skill file is the unit of encoded opinion in Claude Code. Every skill you write is a lesson future-you does not need to re-learn and every other teammate can benefit from. Write them carefully, but write them.


PR Status in Footer - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

When your branch has an open PR, Claude Code surfaces it right in the footer - no more tab-switching to GitHub just to check review status.

## What it does

The footer shows the PR number and a color indicator: green for approved, yellow for changes requested or pending, red for failing checks, and a separate state for merged. You can click the link (in supported terminals) to jump straight to the PR page. Claude can also reference the state in responses.

## When to use it

- Knowing at a glance whether your PR is green without leaving the terminal.
- Monitoring CI status passively while you keep coding.
- Pairing with `gh pr view` for deeper detail when the color shifts.
- Team workflows where review cycle time matters.

## Gotchas

- Requires `gh` to be authenticated and the current branch to match an open PR.
- Status polls on an interval - very recent changes may take a few seconds to show.
- Click-to-open depends on your terminal supporting OSC 8 hyperlinks.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#pr-review-status


Migrating from Cursor to Claude Code
Thu, 23 Apr 2026 00:00:00 GMT

## Why people make this switch

Source check before you migrate: keep the official [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code), [Claude Code setup docs](https://docs.anthropic.com/en/docs/claude-code/setup), [Cursor docs](https://docs.cursor.com), and [Cursor pricing](https://cursor.com/pricing) open. If pricing is the main trigger, compare the current plans against the [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026) before you switch.

If you are reading this, you probably already know why. The most common triggers I hear:

- You tried a parallel agent workflow and found Cursor's chat-first UX limiting
- You hit the token ceiling on Cursor Pro and the bill surprised you
- You want terminal-native tooling that plays well with tmux, worktrees, and cron
- You want to run long-running autonomous sessions that Cursor's architecture does not support

Claude Code is not a strict upgrade over Cursor. It is a different shape. You trade Cursor's visual inline-diff experience for a terminal agent with deeper memory, longer context handling, and better parallelism. If your workflow was already mostly chat-driven with occasional inline completions, the transition is cheaper than it looks.

This guide assumes you are staying on macOS or Linux; Claude Code on Windows is supported but the setup paths differ slightly.

## Before you start

Decide up front which of these three paths you are taking:

1. **Full switch.** Delete Cursor, commit to Claude Code for everything.
2. **Hybrid.** Keep Cursor for visual review and inline edits, use Claude Code for autonomous work.
3. **Evaluation.** Two-week trial, switch back if it does not stick.

Most people land on option 2 for the first month, then drift toward option 1 as they build habits. Know which one you are trying and check in at the two-week mark.

## Step 1: Install Claude Code

```bash
npm install -g @anthropic-ai/claude-code
claude --version
```

Or via Homebrew:

```bash
brew install anthropic/claude-code/claude-code
```

You will need an Anthropic API key or an active Claude Max subscription. Max is the better default for any serious use - the usage limits on metered API use add up faster than you expect for autonomous work. Set the key with:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
# or log in with Max:
claude login
```

## Step 2: Migrate your Cursor Rules

This is the biggest single piece of the transition. Cursor Rules become Claude Code's `CLAUDE.md`.

Find your Cursor Rules:
- `.cursor/rules/*.md` in each project
- `Cursor Settings > AI > Rules for AI` for global rules

For each project with Cursor Rules, create a `CLAUDE.md` at the repo root. Copy over the content, then clean it up using Claude Code conventions:

```markdown
# Project Name



## Stack

- Framework, language, package manager

## Rules

- Concrete rules, one per line, imperative voice
- "Use pnpm, not npm" not "please prefer pnpm"
- "No em dashes" not "avoid excessive punctuation"

## Commands

- `pnpm dev` - local development
- `pnpm test` - run tests
- `pnpm lint` - typecheck and lint

## Architecture notes


```

For global rules, write a `~/.claude/CLAUDE.md`. Claude Code loads this every session.

## Step 3: Rebuild your snippet library

Cursor has a snippets and prompt library feature. Claude Code equivalents:

- **One-shot prompts** that you reuse - save to `~/.claude/prompts/.md`, reference with `@prompts/`
- **Complex procedures** - write them as skills at `~/.claude/skills//SKILL.md` with clear trigger phrases
- **Project-specific prompts** - save to `.claude/prompts/.md` at the repo root

The skills system is the closest analog to Cursor's Composer templates, but it is more powerful: skills load automatically based on the trigger phrase in the description, rather than needing explicit invocation.

## Step 4: Keybindings and editor integration

Claude Code is terminal-native, so your editor keybindings stay where they are. The integration flip is instead at the terminal layer:

- **tmux users** are usually already happy. Claude Code runs in any pane.
- **Alacritty / Kitty / Ghostty users** benefit from the fast redraw when Claude is streaming output
- **Warp users** can use the AI blocks and still run Claude Code side-by-side

If you previously used Cursor's shortcut for "new Composer", build the muscle memory for your terminal equivalent. Most people bind a tmux key to "new Claude Code session" within one week.

## Step 5: Learn the workflow changes

Cursor's core flow is chat with visual diffs, then apply. Claude Code's core flow is agent-driven edit with preview-before-commit. Three habits to build:

**Let the agent do more in one turn.** In Cursor you would often send five small prompts that together accomplish a task. In Claude Code, one well-scoped prompt accomplishes the same task with less back-and-forth. The agent is expected to make multiple related edits without asking.

**Review the diff, not the intent.** Cursor trains you to approve each edit. Claude Code trains you to let a batch of edits happen and then review the resulting diff with `git diff` at the end. This is faster once you trust it.

**Use worktrees for parallel work.** The `git worktree` feature becomes a first-class part of your workflow. You start a feature in a worktree, run Claude Code there, and the main branch stays untouched. This is what Zed's parallel-agents feature automates, but you can do it today with shell commands.

## Step 6: Set up the skills you actually need

Start with three skills most developers reach for:

1. **feature-dev** - end-to-end feature building. Plan, implement, test, review.
2. **code-review** - run a review pass on uncommitted changes or a specific PR.
3. **commit-commands** - draft a commit message and run the commit.

Browse the [skills marketplace](https://skills.developersdigest.tech) for patterns, but start by copying the SKILL.md of a skill close to your need and adapting it. The learning curve is fast - by the third skill you write, you will have internalized the format.

## Step 7: Wire MCP servers

This is where Claude Code pulls ahead of Cursor for most developers. MCP servers give your agent access to external systems - GitHub, Slack, Linear, your database, a search engine. Cursor supports MCP now too, but the ecosystem is deeper and the tooling is more mature in Claude Code.

Start with three MCP servers:

- **context7** or similar docs server for up-to-date library documentation
- **filesystem** server for explicit directory permissions
- **github** server for PR management and issue triage

Install via:

```bash
claude mcp add context7 npx -y @upstash/context7-mcp
```

Browse more at [mcp.developersdigest.tech](https://mcp.developersdigest.tech).

## Step 8: The first week test

After a week on Claude Code, ask:

- Did I feel faster or slower on a typical feature?
- Did I end up opening Cursor for specific tasks? Which ones?
- Did my code review practice survive the agent doing multi-file edits?
- Am I paying more or less than Cursor Pro?

If you find yourself opening Cursor for visual inline diff review, that is fine. Many people settle into "Claude Code for autonomous work, Cursor for inline review" as a long-term hybrid. The real failure mode is opening Cursor because you do not trust Claude Code yet - that is a signal to either watch a tutorial on autonomous mode or to keep two-week trialing.

## Common gotchas

- **You forgot to write CLAUDE.md.** Claude Code without CLAUDE.md is Claude Code without context. It will work, but it will feel dumber than Cursor felt with your Rules loaded. Write the CLAUDE.md on day one.
- **You are still chatting in small turns.** The agent is designed for larger tasks per turn. Batch your requests.
- **You are not using worktrees.** One of the biggest power moves is lost if you run everything on main.
- **You expect visual inline diffs.** Claude Code produces full file edits you review after. Different mental model. Use `git diff` to see what changed.
- **You skipped installing skills.** The out-of-box experience is thin. Install three to five skills on day one.

## When not to switch

A few genuine reasons to stay on Cursor:

- You spend most of your time on small inline edits with tight feedback loops
- You rely heavily on Composer's visual file-selection UI
- Your team's code review workflow is tightly integrated with Cursor's diff viewer
- You are on a Windows machine and have never set up WSL

These are real workflows. Claude Code is not strictly better for every developer. It is better for developers whose work has grown into agent-scale tasks, parallel work, and autonomous runs.

## Further reading

- [Getting Started with Claude Code](/guides/claude-code-getting-started) - the basics, if you skipped them
- [How to Write CLAUDE.md: The Complete Guide](/blog/how-to-write-claudemd-the-complete-guide) - deep dive on the key config file
- [Writing Your First Claude Code Skill](/guides/writing-your-first-claude-code-skill) - build your own skill library
- [Claude Code vs Cursor](/blog/claude-code-vs-cursor-2026) - the direct head-to-head
- [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) - check the budget before changing tools
- [Claude Code usage limits playbook](/blog/claude-code-usage-limits-playbook-2026) - avoid hitting plan limits in week one

The transition is real work. The payoff is usually real. If you are going to try, commit to two weeks of Claude-Code-first usage and then decide.


gh CLI Integration - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The GitHub CLI (`gh`) is the bridge between Claude Code and everything that lives on GitHub - PRs, issues, reviews, releases, workflow runs.

## What it does

Claude uses `gh` through the Bash tool to open PRs, comment on issues, check workflow status, and read review feedback. Because `gh` outputs structured data with `--json`, Claude can parse it cleanly and feed the results into further tool calls. It's how automated PR flows work without hand-rolling the GitHub API.

## When to use it

- Opening PRs with a title and body Claude drafted from the diff.
- Triaging issues, reading comments, posting responses.
- Checking if CI has finished before asking for a review.
- Reading PR review feedback and auto-fixing.

## Gotchas

- `gh` needs to be installed and authenticated separately. Claude can't log you in.
- Rate limits apply the same as with direct API calls.
- Public repo operations (releases, public issues) should require explicit confirmation per repo policy.

Official docs: https://code.claude.com/docs/en/github-actions.md


WebFetch Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

WebFetch pulls content from any URL into the conversation - docs, specs, issue threads, API references.

## What it does

Given a URL, WebFetch downloads the page, extracts the main content, and returns it as text. It handles JavaScript-rendered pages, so SPAs and docs sites with client-side routing work correctly. You can point Claude at an official doc page and have it answer questions grounded in real content instead of stale training data.

## When to use it

- Pulling in docs for a library Claude might not know well.
- Reading an issue or RFC before making a change.
- Quoting from a spec or standard in a PR description.
- Fact-checking before writing code that depends on external behavior.

## Gotchas

- WebFetch is not a general-purpose scraper. Heavy sites or authenticated pages may fail or return partial content.
- Rate limits apply. Batching twenty fetches in a row can get throttled.
- Content is truncated for very long pages. Ask for a specific section if you can.

Official docs: https://code.claude.com/docs/en/tools-reference.md


WebSearch Tool - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

WebSearch runs a search query and returns ranked results with titles, URLs, and snippets. It's the first step when Claude needs to find something on the open web.

## What it does

You pass a query and WebSearch returns a list of results - similar to what you'd see on a search engine page - trimmed to what's useful for follow-up work. Claude typically pairs it with WebFetch: search, pick the best link, fetch, read. Results include a mix of docs, articles, and issue threads depending on the query.

## When to use it

- Finding the current version of an API or library.
- Looking up recent news, outages, or announcements.
- Discovering a doc URL you don't have on hand.
- Comparing multiple sources before committing to an answer.

## Gotchas

- Snippets are short. Always WebFetch the top result if you need real content.
- Results can be region-biased depending on the backend.
- WebSearch is not as precise as a vendor-specific doc search. For library docs, prefer a dedicated source.

Official docs: https://code.claude.com/docs/en/tools-reference.md


CLAUDE.md Files - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

`CLAUDE.md` is the canonical place to put project-specific instructions. Claude reads it automatically every session, so you don't have to re-explain the same context.

## What it does

A `CLAUDE.md` at the repo root becomes part of the system context. Nested `CLAUDE.md` files in subdirectories layer in when Claude works in those paths. Use it for stack overview, conventions, critical rules, common commands, and anything you'd otherwise repeat in every prompt.

## When to use it

- Coding standards that should never be broken (style, banned patterns, design rules).
- Architecture overviews so Claude understands module boundaries.
- Stack-specific commands (how to run tests, build, deploy).
- Team-wide prompts you want every contributor's Claude to see.

## Gotchas

- Huge CLAUDE.md files eat context budget. Keep it focused - 500 lines is already a lot.
- Nested files stack, they don't replace. A conflicting rule deep in the tree still fires.
- It's committed, so don't put secrets or personal preferences there. Use `~/.claude/CLAUDE.md` for those.

Official docs: https://code.claude.com/docs/en/memory.md


.claude/rules Directory - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The `.claude/rules/` directory holds path-scoped instructions that only activate when Claude works in matching files. It keeps CLAUDE.md from ballooning.

## What it does

Each rule file declares a path pattern and a body of instructions. When Claude touches a file that matches, those instructions join the context for that turn. Rules for frontend components don't waste tokens when Claude is editing the backend, and vice versa.

## When to use it

- Language-specific style rules (TypeScript strict mode, Python typing).
- Framework conventions (Next.js app router patterns, Django app structure).
- Per-directory guidance for monorepos with diverse stacks.
- Anything you'd otherwise wrap in "if editing X, do Y" instructions.

## Gotchas

- Overly broad patterns load rules for every file. Be specific.
- Rules stack on top of CLAUDE.md - conflicting rules resolve with the narrowest scope winning.
- Rule files are committed artifacts. Treat them like code, review changes.

Official docs: https://code.claude.com/docs/en/memory.md#organize-rules-with-claude-rules


AGENTS.md - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

`AGENTS.md` is where you define custom subagent types so they're available to every session in the repo.

## What it does

You list subagent definitions - name, description, model, tools, and system prompt - and Claude Code picks them up automatically. When the main agent decides to delegate, these custom types are candidates alongside the built-ins. It's the project-level version of personal subagent definitions.

## When to use it

- Standardizing a "reviewer" or "researcher" agent across the team.
- Locking specific subagents to a narrow toolset for safety.
- Encoding repo-specific workflows as reusable agents.
- Sharing good subagent patterns with every contributor.

## Gotchas

- AGENTS.md is committed. Don't put secrets, API keys, or personal prompts there.
- Changes take effect on session restart, not live.
- Overly custom agents can be worse than the defaults - start with built-ins and specialize only when needed.

Official docs: https://code.claude.com/docs/en/memory.md#agents-md


Auto Memory - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Auto memory records the small facts Claude picks up during a session - how to run tests, which commands failed, what you corrected - and surfaces them on the next session.

## What it does

Claude writes short notes to a per-project memory file when something seems worth remembering: "tests run with `pnpm test --filter web`", "the deploy script needs `DATABASE_URL` exported", "user prefers short commit messages". On the next session, Claude reads those notes into context automatically.

## When to use it

- Projects where build or deploy steps are non-obvious.
- Long-running work that spans many sessions.
- Capturing user preferences without manually writing them into CLAUDE.md.
- Reducing the "what's the test command?" dance.

## Gotchas

- The file grows over time. Review and prune periodically or you'll carry stale notes.
- Auto memory is local by default. Don't rely on it for team-wide context - use CLAUDE.md for that.
- Secrets may slip in if you're not careful. Scan the file before committing it anywhere.

Official docs: https://code.claude.com/docs/en/memory.md#auto-memory


Memory Command - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The `/memory` command is the CLI surface for inspecting and editing the memory layer without opening files manually.

## What it does

Running `/memory` opens a view of the current session's memory sources - CLAUDE.md files, auto memory entries, and any rules that are loaded. You can edit entries, prune stale notes, and trigger a reload. It's faster than hunting for the right file in a nested repo.

## When to use it

- Auditing what Claude currently knows about the project.
- Pruning auto memory that's gone stale.
- Quickly adding a new rule without opening an editor.
- Troubleshooting weird behavior by checking which instructions are active.

## Gotchas

- Changes take effect on the next turn, not retroactively.
- Removing a CLAUDE.md entry doesn't delete the file - it just unloads it for this session.
- Be careful editing live during a turn - partial edits can confuse Claude's current plan.

Official docs: https://code.claude.com/docs/en/memory.md#view-and-edit-with-memory


Context Window Visualization - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Context window visualization turns the abstract "how full is context?" question into a timeline you can actually read.

## What it does

The view shows each turn, tool call, and file read as a block on a timeline, sized by tokens. You can see which reads dominated, where compaction kicked in, and what was dropped. It's the first place to look when Claude starts to feel forgetful or when you want to tune your prompts for efficiency.

## When to use it

- Debugging "Claude forgot X" moments in long sessions.
- Tuning prompts to avoid oversized file reads.
- Planning compaction points for marathon sessions.
- Teaching yourself how context economy actually works.

## Gotchas

- The view samples recent turns - very old history may not render in detail.
- Token counts are estimates. Exact billing still comes from the API.
- Large images or PDFs show up as big blocks. That's real, not a visualization bug.

Official docs: https://code.claude.com/docs/en/context-window.md


Prompt Caching - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Prompt caching reuses large, stable parts of your prompt across turns so you don't pay to re-tokenize them every time.

## What it does

Claude Code marks static context - system prompts, CLAUDE.md, loaded files - as cacheable. Subsequent turns that reuse the same prefix pay a fraction of the normal per-token cost. This is why long sessions don't cost linearly more per turn as context grows.

## When to use it

- Any session with meaningful CLAUDE.md or rule files - caching is already on by default.
- Heavy repos where large file reads recur turn after turn.
- Long debugging sessions where you want predictable costs.
- API-integrated workflows where per-turn cost matters.

## Gotchas

- Cache hits require the prefix to be byte-identical. Small CLAUDE.md edits invalidate the cache.
- Cached entries expire - very long gaps between turns pay full price again.
- Caching is configured per model. Check the model config doc if your numbers look off.

Official docs: https://code.claude.com/docs/en/model-config.md#prompt-caching-configuration


Auto Compaction - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Auto compaction is how Claude Code survives marathon sessions without losing the thread. When the window starts filling, Claude summarizes older turns in place.

## What it does

As context approaches capacity, Claude runs a summarization pass on older turns - preserving key decisions, file paths, and state - while dropping verbose tool output and stale exchanges. The working memory shrinks without losing the important history. PreCompact and PostCompact hooks let you react around the event.

## When to use it

- Long sessions that would otherwise hit the context ceiling.
- Any marathon where you want Claude to stay coherent across many turns.
- Working on tasks that need broad state but not full history.
- Pair with hooks when you want to snapshot, log, or replace compaction behavior.

## Gotchas

- Compaction is lossy. Important details might get summarized away.
- Write critical decisions to disk (notes, TODO.md, commits) so compaction can't drop them.
- Custom compaction via hooks is powerful but easy to get wrong. Start conservative.

Official docs: https://code.claude.com/docs/en/how-claude-code-works.md#when-context-fills-up


Default Permission Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Default mode asks before every consequential action - file writes, shell commands, network calls. It's the safest way to run Claude Code.

## What it does

Each time Claude wants to use a tool that could change your machine or state, you see a prompt: allow, deny, or allow-with-rule. If you add a rule, future identical calls skip the prompt. It's the "new driver" mode - slow but hard to wreck anything with.

## When to use it

- First session on a new project or machine.
- Running a prompt you don't fully trust (random template, unfamiliar skill).
- Working on production systems, infra, or anything costly.
- Teaching a new teammate how Claude Code interacts with their repo.

## Gotchas

- Constant prompts are friction. Graduate to accept-edits or dontask once you've built up a rule set.
- Approvals are session-scoped unless you promote them to permission rules.
- "Allow all once" doesn't save anything. Use it sparingly.

Official docs: https://code.claude.com/docs/en/permission-modes.md


Accept Edits Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Accept Edits mode skips the prompt for routine file edits and safe filesystem commands - the sweet spot between full control and unattended autonomy.

## What it does

File writes and edits inside the project go through without asking. Common filesystem Bash commands like `ls`, `mkdir`, `mv`, and `cp` also skip prompts. Anything that could touch the network, install packages, or run tests still asks - the safety bar is "does it change code or move files around?"

## When to use it

- Normal development flow where you trust the prompt and plan.
- Fast iteration on well-understood changes.
- Teaching Claude a small set of patterns without constant approvals.
- Pairing a human reviewer who watches diffs rather than prompts.

## Gotchas

- Edits still land on disk immediately. Commit often so `git reset` is a real rollback.
- Protected paths are still guarded. Even this mode can't touch `.git` or `.claude` unprompted.
- If a skill auto-invokes risky tools, accept-edits won't save you from prompts - by design.

Official docs: https://code.claude.com/docs/en/permission-modes.md#auto-approve-file-edits-with-acceptedits-mode


Plan Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Plan mode lets Claude think out loud, read code, and propose a full plan before it makes any changes. It's the deliberate, measure-twice-cut-once mode.

## What it does

In plan mode Claude can run read-only tools (Read, Grep, Glob, WebFetch) but is blocked from Edit, Write, and most Bash. The output is a plan - what it would do, in what order, and why. You review the plan, tweak it, then exit plan mode to execute.

## When to use it

- Large refactors where a wrong first step is expensive.
- Exploring a new codebase before touching anything.
- Planning a multi-file change you want a human to sign off.
- Any task where the cost of a bad edit is higher than the cost of a slower first turn.

## Gotchas

- Plan mode can still read sensitive files. It's about preventing writes, not reads.
- A great plan still needs a careful execution turn. Don't skip the review.
- Exiting plan mode without executing is fine - you can use it as pure pre-reading.

Official docs: https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode


Auto Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Auto mode replaces per-action prompts with a background safety classifier. The classifier judges each proposed action and only blocks or escalates the risky ones.

## What it does

When auto mode is on, Claude keeps working without asking for routine tool calls. A lightweight model reviews each call and compares it against your permission rules and safety baselines. Unambiguously safe calls go through; ambiguous or dangerous ones surface as prompts or denials. This is how you get unattended runs without surrendering review.

## When to use it

- Long autonomous tasks where constant prompts would stall you out.
- Background agents in a sandboxed or containerized environment.
- Well-understood repos where you've already tuned permission rules.
- Pairing with hooks that log or checkpoint for audit.

## Gotchas

- Auto mode is a research preview. Behavior can change between releases.
- The classifier isn't perfect. Keep protected paths and critical deny rules in place.
- Prefer sandboxed environments for true unattended runs - auto mode is not the same as bypass mode.

Official docs: https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode


DontAsk Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

DontAsk mode runs Claude Code with zero prompts. Any tool not on your allow list simply fails - no dialog, no escalation.

## What it does

You pre-configure which tools and patterns are allowed. Claude either uses them or fails the turn. No human is in the loop. This is the headless-CI mode, designed for workflow runs, schedulers, and automated pipelines where waiting for a prompt would hang the job.

## When to use it

- GitHub Actions, GitLab CI, or cron-scheduled Claude Code runs.
- Routines that run on infrastructure with no attached terminal.
- Batch jobs where a hang is worse than a clean failure.
- Automations that should fail loudly on unexpected tool needs.

## Gotchas

- Over-tight allow lists break the job for legitimate needs. Err on the side of explicit lists, not bypass.
- Logs matter - you can't see the prompt, so make sure failures write enough detail to debug.
- Combine with bare mode for deterministic runs when hooks and skills might interfere.

Official docs: https://code.claude.com/docs/en/permission-modes.md#allow-only-pre-approved-tools-with-dontask-mode


Bypass Permissions Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Bypass permissions mode disables Claude Code's permission system entirely. It should only run inside an isolated container or VM.

## What it does

Every tool call goes through without evaluation. Protected paths still block - you can't touch `.git`, `.claude`, or similar guarded locations - but otherwise Claude can do whatever it's asked. This is the mode for sandboxed agents where the environment itself is the safety boundary.

## When to use it

- Ephemeral container agents where the filesystem is disposable.
- Dev containers or VMs set up specifically for automated Claude work.
- Anywhere the host is already isolated from anything you care about.
- Never on your personal machine or production server.

## Gotchas

- Protected paths still apply. That's the one safety net you can't turn off.
- Running bypass mode outside a sandbox is how you lose data. The docs are very clear: don't.
- Audit logging still fires. If something goes wrong, the trail exists.

Official docs: https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode


Permission Rules - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Permission rules are how you codify "yes, always run pnpm test" and "no, never touch this directory" without answering prompts each session.

## What it does

Each rule pairs a tool pattern with an action: allow, ask, or deny. Patterns can match Bash commands, file paths, MCP servers, and more - with wildcards for flexibility. Rules live in `settings.json` (project-level) or `settings.local.json` (per-user) and combine with admin-managed rules for teams.

## When to use it

- Allowlisting common commands (`npm run *`, `git status`, `ls *`).
- Denying sensitive paths (production config, secret files).
- Locking Claude to a specific MCP server for a given project.
- Building up a session-to-session baseline of trusted patterns.

## Gotchas

- Order matters. More specific rules should come before broad ones.
- Wildcards can over-grant. Audit your allow list periodically.
- Project rules commit to the repo, so don't put user-specific prefs there. Use `settings.local.json`.

Official docs: https://code.claude.com/docs/en/permissions.md


Protected Paths - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Protected paths are directories Claude Code refuses to modify without explicit, targeted approval - even in bypass mode.

## What it does

`.git`, `.claude`, `.vscode`, and similar metadata directories are guarded by default. Edits or writes to anything inside them require a specific permission grant, not a blanket allow. It's a structural safety net - you can't accidentally rewrite your git history or clobber your Claude config by running a wide prompt.

## When to use it

- Always. Protected paths are on by default and you should leave them on.
- Add your own sensitive paths to the guard list for project-specific safety.
- Pair with audit logging to catch attempts even when denied.
- Keep the guard in place even for trusted agents - the defense layers compound.

## Gotchas

- Some legitimate workflows need to touch `.git` (tools that rewrite hooks, for example). Grant tightly scoped rules for those.
- Protected paths don't prevent reads. Claude can still see what's there.
- Custom protected paths live in settings. Changes apply on session restart.

Official docs: https://code.claude.com/docs/en/permission-modes.md#protected-paths


Sandboxing - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Sandboxing confines Bash tool execution to an allowlist of paths and hosts. It's how you let Claude run commands without granting the shell full reach into your machine.

## What it does

On Linux and macOS, Claude Code can launch Bash calls inside a sandbox that restricts filesystem access to the project directory and network access to a configured allowlist. Commands that try to reach outside the allowed area fail fast with a clear error. This is the strongest containment option short of a full container.

## When to use it

- Granting broad Bash access without worrying about rogue commands.
- Running untrusted or generated scripts safely.
- Multi-tenant environments where you can't trust every skill or prompt.
- Any setup where you want defense-in-depth on top of permission rules.

## Gotchas

- Some tools need network access you might not have whitelisted. Watch for "blocked by sandbox" errors and allowlist specifically.
- Sandboxing has performance overhead - small for most work, noticeable for file-heavy tasks.
- Not available on Windows. Use WSL2 or a container instead.

Official docs: https://code.claude.com/docs/en/sandboxing.md


Model Aliases - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Model aliases let you pick a model by role rather than memorizing version numbers. `opus`, `sonnet`, `haiku`, and `best` all map to the current release of that tier.

## What it does

You set `opus` and Claude Code picks the latest Opus model available on your plan. `sonnet` maps to the latest Sonnet. `best` picks whichever model is highest-tier for your account. Aliases update automatically when Anthropic releases new versions, so you don't rewrite scripts every release.

## When to use it

- Config files that should stay valid across model updates.
- Quick switching during a session via `/model`.
- Scripts and routines that target a tier, not a specific version.
- Teaching examples where you don't want to pin a version.

## Gotchas

- Aliases change under you when a new model ships. If you need stability, pin a specific version ID.
- Some aliases are plan-gated - `best` on a Pro plan differs from `best` on Max.
- Benchmarks that depend on a specific model should never use aliases.

Official docs: https://code.claude.com/docs/en/model-config.md


OpusPlan Alias - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

OpusPlan is a hybrid model setting that uses Opus for planning and Sonnet for execution. You get Opus-quality architecture with Sonnet's speed and cost for the actual work.

## What it does

When you pick OpusPlan, Claude Code runs plan-mode turns and reasoning-heavy steps on Opus, then hands off the concrete tool calls to Sonnet. The split happens automatically - you don't manually swap models. Results tend to be better than pure Sonnet on hard tasks and cheaper than pure Opus.

## When to use it

- Complex refactors where the plan is the hard part but execution is mechanical.
- Cost-conscious workflows that still need strong reasoning.
- Long sessions where flat Opus pricing would be painful.
- Default model for day-to-day work on non-trivial projects.

## Gotchas

- Handoffs between models add a small amount of latency per turn.
- Execution still benefits from extended thinking - don't assume Sonnet can coast.
- Some benchmarks measure pure models only. OpusPlan numbers may not match reported Opus or Sonnet scores.

Official docs: https://code.claude.com/docs/en/model-config.md#opusplan-model-setting


1M Token Context - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The 1M token context window lets Claude Code hold roughly a full mid-size codebase plus history in a single session - no compaction, no chunking.

## What it does

Supported Opus and Sonnet models on qualifying plans offer up to a one-million-token context window. That's enough for a large repository's source, a long conversation history, and tool output without losing earlier turns. Compaction still exists as a safety net but rarely fires during normal work.

## When to use it

- Large codebases you'd otherwise have to chunk.
- Long debugging sessions with lots of file reads.
- Tasks that require tying together evidence from many files at once.
- Agent runs where compaction loss would hurt correctness.

## Gotchas

- More context costs more per turn, even with caching. Watch your spend on marathon sessions.
- Availability depends on your plan and the selected model. Check `/status` if you're unsure.
- Just because the window is big doesn't mean you should fill it. Focused reads still outperform broad ones.

Official docs: https://code.claude.com/docs/en/model-config.md#extended-context


Effort Levels - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Effort levels tune how much reasoning Claude puts into each turn. Low is fast and cheap, max is slow and thorough, and there are three settings between.

## What it does

Each level (`low`, `medium`, `high`, `xhigh`, `max`) adjusts the amount of internal reasoning before Claude commits to a response. Higher levels catch more edge cases and produce better plans on complex work. Lower levels ship faster and cost less for tasks where speed beats depth.

## When to use it

- `low` for trivial edits, one-line fixes, or rote tool calls.
- `medium` for normal day-to-day work.
- `high` or `xhigh` for architecture, tricky refactors, and debugging.
- `max` for the hardest problems where a wrong answer is costly.

## Gotchas

- Higher effort means slower turns. Don't use max for everything.
- Effort scales tokens, which scales cost. Watch the spend on xhigh and max.
- Swapping mid-task can produce mixed quality. Pick a level for a session and stick with it unless a specific step needs more.

Official docs: https://code.claude.com/docs/en/model-config.md#adjust-effort-level


Model Picker (/model) - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The `/model` command opens an interactive picker so you can swap models and effort levels without exiting the session.

## What it does

Run `/model` and Claude Code shows the available models and effort settings with arrow-key navigation. Pick a model, pick an effort level, confirm, and the next turn uses the new config. It's the fastest way to switch between Opus for planning and Sonnet for execution in the same session.

## When to use it

- Starting a task with Opus, then shifting to Sonnet for execution.
- Dropping to haiku for rote work after a hard planning pass.
- Dialing up effort when a task turns out harder than expected.
- Testing how different models handle the same prompt.

## Gotchas

- The current turn keeps the old model. Swaps take effect on the next turn.
- Some models are plan-gated. The picker hides ones you can't use.
- Effort and model aren't independent - not every level is available for every model.

Official docs: https://code.claude.com/docs/en/model-config.md#setting-your-model


Fast Mode - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Fast mode runs Opus with an accelerated inference path - roughly 2.5x the throughput at a higher per-token price.

## What it does

When fast mode is enabled, Claude Code routes Opus calls through a lower-latency backend. You pay more per token, but turns complete faster. Quality matches standard Opus. It's a straight speed-for-cost tradeoff for sessions where wall-clock time matters more than spend.

## When to use it

- Interactive work where latency hurts flow.
- Pair-programming sessions where Claude needs to keep up with you.
- Time-critical debugging or incident response.
- Demos and recordings where dead air looks bad.

## Gotchas

- Fast mode is a research preview. Availability and pricing can change.
- Cost can balloon on long sessions. Watch your `/status` regularly.
- Only Opus is accelerated. Sonnet and Haiku ignore the flag.

Official docs: https://code.claude.com/docs/en/fast-mode.md


Extended Thinking - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Extended thinking gives Claude a dedicated reasoning pass before each response. You trade some latency for significantly better answers on hard problems.

## What it does

When extended thinking is on, Claude runs internal reasoning ahead of its visible response. You can toggle it mid-session with Alt+T. The reasoning itself isn't shown by default but can be surfaced for debugging. On complex architecture, subtle bugs, or multi-step plans, the quality jump is large.

## When to use it

- Design decisions with trade-offs to weigh.
- Bugs that depend on subtle state.
- Refactors spanning many files.
- Code review where you want Claude to spot non-obvious issues.

## Gotchas

- Every turn gets slower with extended thinking on. Turn it off for rote edits.
- Extended thinking consumes thinking tokens, which bill differently. Check your plan.
- It's not a substitute for good prompts - garbage in still produces garbage out, just after longer reasoning.

Official docs: https://code.claude.com/docs/en/common-workflows.md#use-extended-thinking-thinking-mode


Custom Model Option - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Custom model options let you point Claude Code at an alternative endpoint - an LLM gateway, a Bedrock or Vertex deployment, or a proxy - without leaving the CLI.

## What it does

You set environment variables to describe a custom model (name, endpoint, headers, model ID). That option shows up in the `/model` picker alongside the defaults. Claude Code sends the requests through your configured path but keeps the rest of the session behavior identical. It's how teams with internal gateways keep Claude Code on corporate rails.

## When to use it

- Routing through LiteLLM, LangFuse, or a custom gateway for observability.
- Team deployments that require Bedrock, Vertex, or Azure Foundry access.
- Testing a model version that isn't in the default picker.
- Swapping between clouds without editing multiple config files.

## Gotchas

- Gateway auth is your responsibility. Wrong headers mean silent 401s.
- Some features (prompt caching, channels) depend on Anthropic-direct endpoints.
- Model aliases don't transparently resolve on custom endpoints. Use full IDs.

Official docs: https://code.claude.com/docs/en/model-config.md#add-a-custom-model-option


Skills System - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skills turn recurring prompts into named, reusable artifacts. Write one markdown file, invoke it as `/skillname`, and the same prompt runs every time.

## What it does

A skill is a markdown file with frontmatter and a body. The frontmatter describes when to trigger it and what tools it needs; the body is the instructions. Claude auto-loads skills that match the current task, and you can also call them explicitly. Skills can live globally, per-user, or per-project.

## When to use it

- Encoding repeatable workflows (run tests, ship a release, write a blog post).
- Sharing team patterns so everyone gets consistent behavior.
- Replacing long copy-pasted prompt templates.
- Building your own slash commands on top of Claude Code.

## Gotchas

- Auto-invocation depends on the frontmatter description. Vague descriptions mean skills don't fire when expected.
- Skill bodies count against context. Keep them tight - progressive disclosure is your friend.
- Loading order matters when multiple skills could match. Test with explicit invocation first.

Official docs: https://code.claude.com/docs/en/skills.md


Bundled Skills - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code ships with a small library of built-in skills for common workflows. You don't have to write them - they're there from the first session.

## What it does

Skills like `/simplify` (review and simplify recent code changes), `/batch` (group similar edits), `/debug` (enable debug logging), and `/fast` (shift to faster mode) cover the patterns Anthropic has seen repeat across users. Run `/` in an interactive session to browse the full list.

## When to use it

- Quick actions that would otherwise need a paragraph prompt.
- First-time users who want to see what Claude Code can do.
- Troubleshooting - `/debug` is often the fastest path to logs.
- Inspiration for your own skill library.

## Gotchas

- Built-in skill names can collide with custom skills. Use plugin namespaces if you ship your own.
- Some bundled skills require specific plans or features (Opus, fast mode).
- The list evolves between releases. Check the menu after upgrades.

Official docs: https://code.claude.com/docs/en/interactive-mode.md#commands


Skill Invocation - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skills can be invoked two ways: explicitly with a slash command, or automatically when Claude recognizes a matching task.

## What it does

Type `/skillname` and Claude runs that skill with its predefined instructions. Or just describe a task in natural language - Claude reads the available skill descriptions and picks one if it matches. The auto-invocation path is why skill frontmatter quality matters so much.

## When to use it

- Explicit invocation when you know exactly which skill you want.
- Auto-invocation when you want Claude to pick the right pattern unprompted.
- Mixing both: auto for discovery, explicit for reliability.
- Teaching new teammates - show them the slash command, let auto-invocation do the rest.

## Gotchas

- Auto-invocation sometimes picks the wrong skill if descriptions overlap. Be surgical with descriptions.
- Explicit invocation overrides any safety checks in the description heuristics.
- Skills triggered by auto-invocation still respect permission rules and hooks.

Official docs: https://code.claude.com/docs/en/skills.md


Skill Frontmatter - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skill frontmatter is a YAML block at the top of a skill file that controls how the skill runs and when it triggers.

## What it does

The frontmatter declares the skill's name, description, model preference, effort level, allowed tools, MCP servers, and other per-skill config. Claude reads these fields to decide when to auto-invoke the skill and how to execute it. The description field is especially important - it's what Claude uses to match user intent to the skill.

## When to use it

- Locking a skill to a specific model or effort level for predictable results.
- Restricting tools so a skill can't do more than it should.
- Tuning descriptions for reliable auto-invocation.
- Declaring required MCP servers so the skill fails fast if they're missing.

## Gotchas

- Bad descriptions lead to bad auto-invocation. Write them like ads: clear triggers and scope.
- Tool restrictions apply strictly. If a skill tries to use an unlisted tool, it fails.
- Model settings in frontmatter can override the session's current model - intentional, but surprising.

Official docs: https://code.claude.com/docs/en/skills.md#frontmatter-reference


Skill Arguments - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skill arguments let you parameterize a skill so it can be reused across different inputs without duplicating the whole file.

## What it does

You define placeholders in the skill body and users pass values when they invoke the skill. For example, `/newblog "topic"` can substitute the topic into the instructions. The argument syntax is documented with the skill's description so users know what to pass. It turns static skills into small functions.

## When to use it

- Skills that operate on a variable target (filename, topic, URL).
- Parameterized workflows like "write a blog about X" or "review file Y".
- Reducing skill proliferation - one parametric skill beats ten near-identical ones.
- Encoding team conventions with per-invocation overrides.

## Gotchas

- Document argument names and formats in the skill description or the skill's README.
- Quoting matters. Arguments with spaces need quotes on the command line.
- Optional arguments still require a placeholder strategy - decide on defaults explicitly.

Official docs: https://code.claude.com/docs/en/skills.md#pass-arguments-to-skills


Disable Model Invocation - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Disabling model invocation keeps a skill loaded but invisible to Claude's auto-selector. It only runs when a human types `/skillname`.

## What it does

Set the invocation control in the skill's frontmatter and Claude won't see the skill during its intent matching pass. The skill is still registered and can be called explicitly. This is useful for skills that have side effects you don't want auto-triggered, or for internal tooling you only want invoked deliberately.

## When to use it

- Destructive or expensive skills you want called consciously.
- Skills whose descriptions would match too aggressively.
- Internal or experimental skills not ready for auto-use.
- Skills that should always run through a specific human-driven workflow.

## Gotchas

- Users still have to know the command exists. Document it somewhere findable.
- Disabling invocation doesn't disable the skill entirely - it's still loaded in context.
- If you want a skill fully inert, remove it from the skills directory or gate with a feature flag.

Official docs: https://code.claude.com/docs/en/skills.md#control-who-invokes-a-skill


Skill Pre-Approval - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skill pre-approval lets you grant tool permissions upfront when a skill runs, so the skill's routine actions don't trigger prompts.

## What it does

Declare a pre-approval list in the skill's frontmatter. When the skill fires, those tool invocations skip the permission dialog. The rest of the session still follows normal rules. This is how well-tested skills stay fast without forcing users into global allow modes.

## When to use it

- Skills with a fixed, well-understood set of tool calls.
- Repeatable workflows where prompts would break flow.
- Team-shipped skills where you've already vetted the behavior.
- CI-adjacent skills that must not hang on approvals.

## Gotchas

- Pre-approval widens the blast radius if the skill is compromised. Review changes carefully.
- Grants are scoped to the skill's execution, not the whole session. Good defense-in-depth.
- Permissions still can't override protected paths.

Official docs: https://code.claude.com/docs/en/skills.md#pre-approve-tools-for-a-skill


Skill in Subagent - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Skills can run inside a forked subagent context so they don't bloat the main conversation. The main session gets the summary, not the intermediate steps.

## What it does

Mark a skill as `context: fork` and Claude spawns a subagent to execute it. The subagent has its own context window, runs to completion, and returns a concise result. The main session only sees the return value, not the detailed reasoning or tool output. It's how you keep large investigations from eating the primary context.

## When to use it

- Research tasks that would otherwise fill context with reads.
- Large audits or scans where you only care about the conclusion.
- Parallel fan-out where each branch can be summarized independently.
- Keeping the main session focused on your actual coding work.

## Gotchas

- Subagent context is ephemeral. Important findings need to land in a file or the return value.
- Forking costs a turn's worth of setup latency.
- Nested forks work but compound cost and latency. Use sparingly.

Official docs: https://code.claude.com/docs/en/skills.md#advanced-patterns


Live Skill Discovery - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code watches your skills directory for changes. Edit a skill file and the session picks up the new version without a restart.

## What it does

On file save, Claude Code notices the change and reloads the skill's frontmatter and body. New skills added to the directory show up immediately. Removed skills disappear. This makes skill authoring feel fast - edit, save, try it, edit again.

## When to use it

- Iterating on a new skill during a live session.
- Testing description wording for auto-invocation.
- Updating a team-shared skill and seeing the effect without restarting.
- Pair-programming with a skill author alongside a Claude session.

## Gotchas

- In-flight turns don't hot-reload. The change applies on the next invocation.
- Syntax errors in frontmatter silently disable the skill. Check the `/mcp` or skill menu to see what actually loaded.
- If you rename a skill mid-session, old references may fail until reload.

Official docs: https://code.claude.com/docs/en/skills.md#live-change-detection


Subagents - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Subagents are isolated Claude Code instances the main session can spawn for focused work. They have their own context, their own tools, and return a clean result when done.

## What it does

Claude delegates a task to a subagent with a specific prompt and toolset. The subagent runs in isolation - its reads, edits, and reasoning don't land in the main context. When it finishes, it returns a summary. This is the building block for parallel work, research fan-outs, and context hygiene in long sessions.

## When to use it

- Research tasks that would otherwise swell the main context.
- Parallel exploration across several files or topics.
- Delegating a concrete subtask while you keep the bigger picture.
- Running specialized roles (reviewer, auditor, researcher) with different system prompts.

## Gotchas

- Subagent output is what the main session sees - make sure the return is informative.
- Each subagent is a separate model call. Spawning too many inflates cost and time.
- Subagents don't share memory with the parent unless you configure persistent memory.

Official docs: https://code.claude.com/docs/en/sub-agents.md


Built-in Subagents - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Claude Code ships with a handful of pre-built subagent types so you can delegate without writing your own first.

## What it does

Built-in subagents include roles like researcher (gathers context without editing), auditor (reviews code for issues), and reviewer (checks changes). Each has a tuned system prompt and tool allowlist. You invoke them by name or let the main agent pick the right one for the task.

## When to use it

- Starting point before you build custom subagent definitions.
- Situations where you just need a clear role label, not a bespoke prompt.
- Team onboarding - everyone has the same built-in types available.
- Quick delegation without the overhead of writing a new agent.

## Gotchas

- Built-ins are generic. For repeat workflows, a custom subagent usually wins.
- The list and behavior of built-ins evolves between releases. Don't hard-code assumptions.
- You can shadow a built-in with a same-named custom agent - useful or confusing depending on context.

Official docs: https://code.claude.com/docs/en/sub-agents.md#built-in-subagents


Custom Subagent Types - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Custom subagents let you define your own roles - "migration agent", "doc writer", "test generator" - and invoke them anywhere in the session.

## What it does

Create a markdown file with a name, description, system prompt, tool allowlist, and model preference. Drop it in the project's `AGENTS.md` or your user-level agents directory. Claude treats it as a first-class delegation target from that point on.

## When to use it

- Encoding repeatable roles your team uses often.
- Locking down tool access per role for safety.
- Building specialized agents for domain work (security review, migration, copyediting).
- Reducing the cognitive load of "how do I prompt this kind of task?"

## Gotchas

- Keep descriptions crisp - that's what Claude matches against to pick the right agent.
- Overlapping descriptions cause wrong picks. Test with explicit invocation first.
- Agents live on disk. Updates need a reload on older Claude Code builds.

Official docs: https://code.claude.com/docs/en/sub-agents.md#quickstart-create-your-first-subagent


Subagent Frontmatter - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Subagent frontmatter is the YAML block that configures how a custom subagent behaves and what it can touch.

## What it does

The frontmatter declares model, effort, allowed tools, MCP servers, skills, memory behavior, and scoping (project vs user). It's the contract between the subagent definition and the runtime. Claude honors every field when it spawns the agent, so getting the frontmatter right is how you build safe, predictable roles.

## When to use it

- Every custom subagent definition needs frontmatter - this is your starting point.
- Tuning which MCP servers a subagent can reach.
- Pinning a subagent to a specific model for consistent output.
- Enabling persistent memory for long-lived roles.

## Gotchas

- Tool allowlists are strict. A missing entry means the subagent fails the call, not that it asks.
- Model fields override session defaults when the subagent runs.
- Misspelled frontmatter fields silently fail. Run the agent once to confirm behavior.

Official docs: https://code.claude.com/docs/en/sub-agents.md#supported-frontmatter-fields


Subagent Tool Restrictions - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Tool restrictions let you cap what a subagent is allowed to do. A "read-only researcher" literally can't write to disk if you don't include Edit or Write.

## What it does

In the subagent's frontmatter, you list the exact set of tools the agent may use. Every other tool call from that agent fails immediately. This is the cleanest way to build roles with least-privilege guarantees - the safety is structural, not based on hoping Claude doesn't reach for a forbidden tool.

## When to use it

- Researcher and auditor roles that should never write code.
- Tightly scoped agents for sensitive tasks (compliance checks, logs).
- Shared team agents where different contributors will invoke them.
- Defense in depth alongside permission rules.

## Gotchas

- Over-restricted agents fail tasks in confusing ways. Err toward inclusion for genuine needs.
- Tool restrictions don't limit what the subagent can read - they limit what it can call.
- Adding tools later is easy; taking them back is harder once workflows depend on them.

Official docs: https://code.claude.com/docs/en/sub-agents.md#control-subagent-capabilities


Subagent MCP Scoping - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP scoping lets you expose a given MCP server only to the subagents that should see it. The main session - and other subagents - don't even know it exists.

## What it does

You declare the MCP servers a subagent has access to in its frontmatter. Other agents and the main session operate without those tools loaded. This is how you keep a database-writing MCP out of the researcher role, or a secrets-access MCP limited to a single privileged agent.

## When to use it

- Isolating sensitive MCP servers to a narrow set of roles.
- Reducing context overhead by not loading irrelevant MCP tools in every agent.
- Building specialist agents that pair naturally with specific integrations.
- Team setups where different roles should see different data.

## Gotchas

- Scoping is enforced at load time. If you change scopes mid-session, restart.
- Unknown MCP server names in frontmatter fail silently. Double-check spelling.
- Don't rely on scoping alone for secrets - combine with network and auth boundaries.

Official docs: https://code.claude.com/docs/en/sub-agents.md#scope-mcp-servers-to-a-subagent


Subagent Persistent Memory - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Persistent memory lets a subagent carry state forward between invocations. A researcher agent can remember what it's already looked into; a reviewer can remember your house style.

## What it does

Enable persistent memory in the subagent frontmatter and Claude writes summaries to a scoped memory file after each run. On the next invocation, the agent loads those notes before it begins. It's auto-memory, but scoped to the agent identity rather than the project.

## When to use it

- Agents that do the same job repeatedly and benefit from recall.
- Multi-session work where you want continuity without copy-pasting context.
- Reviewer or auditor agents that should learn your preferences over time.
- Fan-out patterns where each worker builds on prior runs.

## Gotchas

- Memory grows over time. Prune stale entries or it starts to slow down invocations.
- Persistent memory isn't magic - the agent still needs relevant instructions each call.
- Scope matters. Project-scoped memory shouldn't leak personal preferences; user-scoped shouldn't leak project data.

Official docs: https://code.claude.com/docs/en/sub-agents.md#enable-persistent-memory


Subagent Context Isolation - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Context isolation is the defining feature of subagents. Work done inside a subagent stays there - only the summary comes back.

## What it does

When you delegate to a subagent, its reads, tool output, and intermediate reasoning don't count against the main session's context. The main agent gets a condensed return value. This means a thousand-line exploration can resolve to a short answer without eating your window.

## When to use it

- Any investigation that would otherwise clutter context.
- Large codebases where reading enough to answer a question costs a lot.
- Parallel fan-out with many independent branches.
- Keeping the main session focused on coding rather than scanning.

## Gotchas

- Anything you need later has to make it into the subagent's return. If you lose it, you lose it.
- Subagent isolation isn't a security boundary - it's a context boundary.
- Over-delegating can fragment work. Some tasks want the main agent in-context.

Official docs: https://code.claude.com/docs/en/sub-agents.md


Resume Subagents - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

You can resume a subagent's work later, in a new session, without losing its state. The subagent picks up where it stopped.

## What it does

Claude Code saves subagent sessions to disk. A resume call restores the subagent's context, recent tool output, and in-flight task list. You can continue the investigation, adjust the prompt, or let the subagent finish a job it paused mid-run. This is the recipe for long-running specialist agents that span days.

## When to use it

- Long-running research tasks that need human checkpoints.
- Migration or audit work that can't finish in one session.
- Parallel agent teams where some workers stall and need a human push.
- Anything where "start again from scratch" is wasteful.

## Gotchas

- Resumed context is what the subagent had at pause. Anything that changed in the repo since isn't reflected until the next read.
- Very old resumes may reference files that have moved or been deleted.
- Resume is per-subagent. Resuming one worker doesn't resume the whole team.

Official docs: https://code.claude.com/docs/en/sub-agents.md#resume-subagents


Hooks System - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Hooks are the event system that lets you run code when Claude Code does things - start sessions, call tools, finish turns, request permissions.

## What it does

You wire up hooks in settings.json. Each hook binds to an event (SessionStart, PreToolUse, Stop, and dozens of others) and runs a shell command, a prompt, or a subagent. Hooks can allow, deny, modify, or observe the event. This is how you enforce policy, capture telemetry, customize behavior, and integrate Claude Code into your team's workflow.

## When to use it

- Enforcing custom policies that permission rules can't express.
- Logging and telemetry for audit and observability.
- Automating recurring actions (post-edit lint, pre-commit tests).
- Integrating with external systems (Slack notifications, ticket updates).

## Gotchas

- Hooks run with your permissions and touch real systems. Treat them like any automation.
- Synchronous hooks block turns until they return. Use async hooks for slow operations.
- Misconfigured hooks can wedge a session. Keep them testable and fail-open where appropriate.

Official docs: https://code.claude.com/docs/en/hooks.md


SessionStart Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

SessionStart fires once when Claude Code starts a session. It's the place for environment setup, secret loading, and "run this every time" initialization.

## What it does

The hook runs after config loads but before the first user prompt. It can export environment variables that persist across Bash calls, print a welcome banner, run a health check, or pull a secret from a vault. Its return value can inject context into the session.

## When to use it

- Loading API keys or credentials from a secret manager.
- Pulling the latest CLAUDE.md or rules from a central source.
- Warming caches for tools Claude will likely need.
- Emitting a project-specific banner so you know which context you're in.

## Gotchas

- Slow SessionStart hooks make startup feel sluggish. Keep them fast or run async.
- Failing hooks can block a session. Default to fail-open unless failure should truly stop work.
- Env vars set here persist into Bash calls but not into shells you launched before the session started.

Official docs: https://code.claude.com/docs/en/hooks.md#sessionstart


SessionEnd Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

SessionEnd fires when Claude Code is shutting down a session - clean exit or otherwise. It's your last chance to flush logs, stop services, or summarize work.

## What it does

The hook runs after the last turn completes and before the process exits. It can record analytics, push auto-memory updates, kill orphaned background processes, or write a session summary to disk. Output goes to logs, not to the user - the session's already done.

## When to use it

- Cleaning up background tasks Claude spawned during the session.
- Writing a short summary of what changed to a handoff file.
- Flushing metrics to an observability backend.
- Closing any connection or file handle the session opened.

## Gotchas

- SessionEnd may fire after a crash or interrupt. Make the hook resilient.
- Long SessionEnd hooks delay process exit. Don't block on network calls if you can avoid it.
- Some signals kill the process before the hook can run. Critical cleanup needs defense-in-depth.

Official docs: https://code.claude.com/docs/en/hooks.md#sessionend


UserPromptSubmit Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

UserPromptSubmit runs right after you hit Enter and before Claude sees the prompt. Use it to validate, transform, or block what goes to the model.

## What it does

The hook receives the submitted prompt. It can allow it through unchanged, modify it (append project context, redact secrets), or reject it with a reason. This is the cleanest way to enforce team prompt policies, strip sensitive data, or inject reminders into every turn.

## When to use it

- Auto-appending "run tests after your changes" to every prompt.
- Redacting secrets like tokens or passwords before they hit the model.
- Blocking prompts that match a forbidden pattern (e.g., "delete production").
- Injecting per-prompt context like the current branch or PR number.

## Gotchas

- Heavy transformations confuse users when the model responds to something they didn't type. Keep transforms visible.
- Synchronous hooks add latency to every turn. Stay fast.
- Rejection messages should be clear - "denied by policy: reason" beats a silent block.

Official docs: https://code.claude.com/docs/en/hooks.md#userpromptsubmit


UserPromptExpansion Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

UserPromptExpansion runs when a slash command (including a skill) expands into its full prompt. It's your hook point between "user typed /foo" and "Claude starts reasoning".

## What it does

The hook sees the expanded prompt from a slash command. It can modify the expansion, block the command, or attach context only relevant to that command. This is how you enforce per-skill rules - maybe your `/deploy` skill should always refuse on Fridays, or your `/merge` skill should always require a PR number.

## When to use it

- Enforcing constraints on specific skills (never run destructive skills in main branch).
- Attaching dynamic context to certain commands (pull current config, add today's date).
- Auditing slash command usage across a team.
- Building guardrails around team-shared skills.

## Gotchas

- The hook fires for every matching expansion, including auto-invocations. Scope triggers carefully.
- Blocking without explanation frustrates users. Always return a reason.
- Expansion-time hooks don't see the user's raw intent, only the resolved skill body.

Official docs: https://code.claude.com/docs/en/hooks.md#userpromptexpansion


PreToolUse Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PreToolUse is the most powerful hook point. Every tool call flows through it, and the hook can allow, deny, defer, or rewrite the call before it executes.

## What it does

The hook receives the tool name and arguments. Return values drive decision: allow the call as-is, deny with a reason, defer (ask the user), or modify (adjust arguments before execution). This is the extension point for custom policy engines, dynamic rewriting, and fine-grained safety controls.

## When to use it

- Enforcing "no Bash commands from this list" policies.
- Rewriting edits to match house style automatically.
- Auditing every tool call to an external system.
- Deferring specific calls to a human reviewer even in auto mode.

## Gotchas

- Every tool call pays the hook's latency cost. Keep the hook fast.
- Modifying arguments without telling the user can cause confusion. Log changes clearly.
- A bad hook can block every tool call and wedge the session. Test in a throwaway session first.

Official docs: https://code.claude.com/docs/en/hooks.md#pretooluse


PostToolUse Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PostToolUse runs after a tool call completes successfully. Use it to provide feedback, run side effects, or kick off follow-up actions.

## What it does

The hook receives the tool name, arguments, and result. It can log the call, inject a follow-up instruction into the conversation, run a linter after every edit, or push a notification. Unlike PreToolUse, it can't prevent the call - it reacts to what already happened.

## When to use it

- Running a formatter or linter after every file edit.
- Auto-staging files in git after Claude writes them.
- Posting a Slack notification when deploys happen.
- Auditing tool outcomes to an observability pipeline.

## Gotchas

- The hook runs on every success, which can be many times per turn. Stay fast.
- Post-hooks can't roll back the tool call. If something was dangerous, catch it in PreToolUse.
- Injecting too much context via the hook inflates the next turn's tokens.

Official docs: https://code.claude.com/docs/en/hooks.md#posttooluse


PostToolUseFailure Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PostToolUseFailure fires when a tool call fails - nonzero exit, exception, timeout. It's your hook for alerting, retry logic, and failure-specific telemetry.

## What it does

The hook receives the tool, arguments, and error details. It can log the failure, send an alert, advise Claude on how to proceed, or even suggest an alternative approach. It runs in the failure path only, so you can keep logic focused on the unhappy case.

## When to use it

- Sending pager alerts when deploy tools fail.
- Auto-logging to Sentry or a similar backend.
- Injecting helpful context when a common failure happens ("run `pnpm install` first").
- Counting failures per tool for diagnostic dashboards.

## Gotchas

- Don't spam alerts for expected failures (test assertions, known flaky commands).
- Injecting advice can loop Claude back into the same failure. Include a max-retry check.
- Failure details may contain sensitive output. Scrub before sending to external systems.

Official docs: https://code.claude.com/docs/en/hooks.md#posttoolusefailure


PermissionRequest Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PermissionRequest runs when Claude Code is about to show the user a permission dialog. The hook can intercept - auto-approving or auto-denying based on custom logic.

## What it does

The hook sees the tool, arguments, and reason for the prompt. It can allow, deny, or pass through to the user. This is how you implement policy that's smarter than static permission rules - decisions based on the current branch, time of day, remote git state, or anything else you can script.

## When to use it

- Conditional auto-approval (only on feature branches, never on main).
- Integrating with an external approval system for sensitive tasks.
- Enforcing team policies that vary by project phase.
- Building smarter "auto mode" behavior than the built-in classifier.

## Gotchas

- Automating approvals removes the human safety net. Log every decision.
- Long-running hooks stall the session while the user waits.
- A hook that auto-denies too aggressively will be worse than the default prompts.

Official docs: https://code.claude.com/docs/en/hooks.md#permissionrequest


PermissionDenied Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PermissionDenied runs after a permission rule, auto-mode classifier, or hook denies a tool call. Use it to observe, escalate, or explain.

## What it does

The hook receives the denial reason and the rejected tool call. It can log the event, notify a human, ask Claude to try a different approach, or surface a targeted error. It's the observability hook for a denial-heavy workflow.

## When to use it

- Tracking denied actions to audit how tightly your policy is tuned.
- Paging a reviewer when a specific denied pattern happens.
- Teaching Claude alternatives on a first denial.
- Building dashboards for "what is Claude trying to do that's blocked?"

## Gotchas

- Denials are noisy in tight environments. Filter before alerting.
- Teaching Claude an alternative on every denial can loop. Cap retries.
- Logs from this hook may contain sensitive reasons. Scrub before shipping to analytics.

Official docs: https://code.claude.com/docs/en/hooks.md#permissiondenied


SubagentStart and SubagentStop Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

SubagentStart and SubagentStop hooks fire around subagent lifecycles - at spawn and at completion.

## What it does

SubagentStart runs when the main agent delegates to a subagent. It receives the subagent definition and the initial task. SubagentStop runs when the subagent finishes. Together they let you track parallel work, enforce concurrency limits, log per-agent metrics, or annotate the returned result before it reaches the main session.

## When to use it

- Counting active subagents to cap parallelism.
- Tagging logs with the subagent name for observability.
- Adding project-specific context to every subagent prompt via Start.
- Normalizing or sanitizing subagent return values via Stop.

## Gotchas

- Many subagents running in parallel means these hooks fire a lot. Keep them lightweight.
- Start hooks that modify the task too aggressively can confuse the subagent.
- Stop hooks that rewrite results hide what the subagent actually said. Log originals.

Official docs: https://code.claude.com/docs/en/hooks.md#subagentstart


TaskCreated and TaskCompleted Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

TaskCreated and TaskCompleted hooks plug into the session's task-list events - when Claude adds work to do or checks something off.

## What it does

TaskCreated fires when Claude writes a new task to the list. TaskCompleted fires when one is finished. Hooks can log task activity, sync the list to an external issue tracker, trigger notifications, or gate on approvals before a task is considered done.

## When to use it

- Syncing the task list to Linear, GitHub Projects, or Jira.
- Alerting a reviewer when a sensitive task completes.
- Generating a daily digest of work Claude actually finished.
- Enforcing team conventions around task granularity.

## Gotchas

- Don't block TaskCompleted with a heavy external sync - it delays every turn.
- If you sync to an external system, handle dedup. Task IDs can change across sessions.
- Very short tasks create a lot of events. Consider batching.

Official docs: https://code.claude.com/docs/en/hooks.md#taskcreated


Stop Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The Stop hook fires when Claude is about to stop responding at the end of a turn. It can observe the finish, or actively block the stop and push Claude to keep going.

## What it does

Hooked on Stop, you can inspect the final response, check if a required condition is met, and if not, return instructions telling Claude what's still missing. The turn continues until the hook allows it to stop, or until a loop-prevention cap fires. This is how you enforce "don't stop until tests pass" style policies.

## When to use it

- Requiring tests pass before Claude declares a task done.
- Enforcing completion checklists (tests + types + lint).
- Forcing specific output formats before a turn closes.
- Building review bots that push Claude to iterate.

## Gotchas

- It's easy to loop infinitely if the stop condition is unreachable. Always include a retry cap.
- Heavy Stop checks make every turn feel slow. Keep them fast and cached where possible.
- A noisy Stop hook that always demands more is worse than no hook at all.

Official docs: https://code.claude.com/docs/en/hooks.md#stop


FileChanged Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

FileChanged hooks react to external changes in the project - another editor saved a file, git pulled new commits, a build wrote an artifact.

## What it does

You declare paths or patterns to watch. When Claude Code detects a change, the hook fires with the path and the kind of change. It can update the model's context, invalidate caches, or trigger a follow-up action. It's how Claude stays aware of what's happening outside its own edits.

## When to use it

- Reacting to lockfile changes to suggest a reinstall.
- Reloading config when `.env` or settings files shift.
- Notifying Claude when a teammate pushed a fresh branch state.
- Building IDE-like responsiveness in CLI sessions.

## Gotchas

- Watching too many paths causes noise. Start narrow.
- FileChanged events can fire during Claude's own edits - be careful not to loop.
- Debounce rapid-fire events (package managers that touch many files at once).

Official docs: https://code.claude.com/docs/en/hooks.md#filechanged


ConfigChange and InstructionsLoaded Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

ConfigChange and InstructionsLoaded hooks react to updates in settings or memory files during an active session.

## What it does

ConfigChange fires when `settings.json` or related files change. InstructionsLoaded fires when CLAUDE.md, rules, or agents definitions are (re)loaded. The hooks receive what changed and can respond - log the diff, notify the user, invalidate internal state, or reject the change for the current session.

## When to use it

- Auditing config drift during long sessions.
- Warning users that their rules changed mid-run.
- Refreshing tool allowlists when MCP config is reloaded.
- Syncing effective config to an external monitoring system.

## Gotchas

- These hooks can fire during Claude's own edits to config files. Expect recursion.
- Changes that invalidate the session (new CLAUDE.md rule conflicting with in-flight work) need explicit handling.
- Heavy reload logic slows startup and reloads. Keep it minimal.

Official docs: https://code.claude.com/docs/en/hooks.md#configchange


PreCompact and PostCompact Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

PreCompact and PostCompact hooks let you control or observe when Claude compacts context to stay within the window.

## What it does

PreCompact fires just before Claude summarizes older turns. It can block the compaction, customize the summary strategy, or persist important context before it gets condensed. PostCompact fires after compaction completes, receiving the before/after sizes and the summary used. It's the clean hook point for "make sure this important decision survives compaction".

## When to use it

- Snapshotting state to disk before a compaction you're worried about.
- Injecting explicit "keep this" notes before summarization.
- Measuring compaction frequency for context-efficiency tuning.
- Auditing what the summarizer is choosing to forget.

## Gotchas

- Aggressive PreCompact logic can delay long turns noticeably.
- Custom compaction strategies are powerful and easy to get wrong. Start with the default.
- PostCompact runs with the new, smaller context. The hook can't reference what was dropped.

Official docs: https://code.claude.com/docs/en/hooks.md#precompact


Elicitation Hook - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The Elicitation hook intercepts when an MCP server asks the user a question. The hook can provide the answer automatically or pass through to a prompt.

## What it does

MCP servers sometimes need additional input - a confirmation, a choice, a free-text value. Normally Claude surfaces the request as a dialog. The Elicitation hook can answer it programmatically based on the question, the server, or the current state, skipping the dialog and keeping the session flowing.

## When to use it

- Auto-answering routine MCP confirmations in a trusted context.
- Keeping headless sessions from hanging on MCP prompts.
- Team policies where a specific MCP server's questions have a canonical answer.
- Integrating MCP workflows with your own approval backend.

## Gotchas

- Auto-answering without care defeats the MCP server's safety intent. Scope carefully.
- Not every elicitation has a sensible automated response. Some must reach a human.
- Logging answers is important for audit - you're effectively speaking for the user.

Official docs: https://code.claude.com/docs/en/hooks.md#elicitation


Command Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Command hooks are the simplest hook flavor: on the event, run a shell command, and use its exit code and stdout as the result.

## What it does

You declare a command in the hook config. Claude Code runs it when the event fires, passing context via environment variables (tool name, arguments, file paths, etc.). The command's exit code determines allow or deny, and its stdout can contribute messages back to the session. This is the bash-friendly way to wire up quick hooks without learning a new runtime.

## When to use it

- Simple side effects like logging, notifications, or external integrations.
- Team hooks written in whatever language the team prefers.
- Reusing existing scripts you already have for policy or automation.
- Fast prototyping before moving to prompt-based or agent-based hooks.

## Gotchas

- Shell quoting and escaping is still shell. Test with edge-case arguments.
- Slow scripts delay every matching event. Run long work async.
- Env var names and JSON payload shape matter - check the hooks doc for exact fields.

Official docs: https://code.claude.com/docs/en/hooks.md#command-hook-fields


Prompt-Based Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Prompt-based hooks let Claude evaluate the event with a short prompt, making allow/deny decisions that are too nuanced for pure shell scripts.

## What it does

Instead of a shell command, you provide a prompt. Claude Code sends the event context to a lightweight model call, and the response shapes the hook's decision. The model can reason about the content of a prompt or tool call, not just regex-match it. This opens up semantic policies - "block this if it looks like a destructive production action".

## When to use it

- Policies that require judgment ("is this prompt about the production DB?").
- Content classification that a regex can't do reliably.
- Advisory hooks that suggest improvements rather than block.
- Cases where the event context is too complex for simple checks.

## Gotchas

- Prompt-based hooks add model latency to every fire. Pick a cheap, fast model.
- Non-determinism is a feature and a bug - the same event might decide differently twice.
- For safety-critical policy, pair with a deterministic shell hook for defense in depth.

Official docs: https://code.claude.com/docs/en/hooks.md#prompt-based-hooks


Agent-Based Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Agent-based hooks spawn a subagent to handle the hook, giving you full tool access and multi-step reasoning inside a hook.

## What it does

When the event fires, Claude Code hands off to a subagent with its own tools, context, and system prompt. The subagent can read files, run commands, consult external APIs, and return a decision. This is overkill for logging but perfect for rich policy - "review this diff for security issues before allowing the write".

## When to use it

- Policies that need to read multiple files before deciding.
- Advisory reviewers that post comments rather than block.
- Complex approval flows that can't fit in a single prompt.
- Integrating an auditor role into the hook pipeline.

## Gotchas

- Agents in hooks are slow relative to command or prompt hooks. Use sparingly.
- Each hook fire costs a subagent spawn. Cache where possible.
- Circular dependencies (hook agent triggers same hook) are easy to write and hard to debug.

Official docs: https://code.claude.com/docs/en/hooks.md#agent-based-hooks


Async Hooks - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Async hooks detach from the event and run in the background so the session keeps moving. Good for telemetry, notifications, and anything Claude doesn't need to wait on.

## What it does

Mark a hook async and Claude Code launches it but doesn't wait for the exit code. The session proceeds; the hook runs on its own. If the hook fails, it fails silently - the session never knew. This is the right pattern for fire-and-forget side effects.

## When to use it

- Shipping logs to an analytics backend.
- Posting Slack notifications when something happens.
- Kicking off secondary builds or caches.
- Anything where the user shouldn't feel the latency.

## Gotchas

- Async hooks can't block or modify the event. If you need to prevent something, use a sync hook.
- Failures don't surface. Check logs separately to catch problems.
- Too many async hooks firing quickly can starve system resources.

Official docs: https://code.claude.com/docs/en/hooks.md#run-hooks-in-the-background


MCP Servers - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP (Model Context Protocol) servers are how Claude Code reaches anything outside the repo - databases, APIs, internal services, file systems, you name it.

## What it does

An MCP server exposes tools, resources, and prompts over a standard protocol. Claude Code connects to the server, loads the available capabilities, and makes them available as tools within the session. MCP is open and multi-vendor, so the same server works with different clients.

## When to use it

- Wiring up databases, issue trackers, dashboards, or internal APIs.
- Exposing legacy systems to Claude Code without writing custom integrations.
- Sharing integrations across the team via `.mcp.json` in the repo.
- Building your own domain-specific tools that feel native.

## Gotchas

- MCP servers run with their own auth. Misconfig means you silently lose access.
- Loaded MCP tools count against context and can slow tool selection. Use tool search for large suites.
- Remote MCP servers introduce network dependency. Plan for offline or fallback behavior.

Official docs: https://code.claude.com/docs/en/mcp.md


MCP Installation Scopes - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP servers can live at different scopes - just this session, just this project, all your projects, or bundled in a plugin - and the scope determines who and what sees them.

## What it does

Local scope loads a server for a single session. Project scope commits it to the repo so everyone on the team gets it. User scope lives in your home config and follows you across repos. Plugin scope bundles MCP as part of a distributable plugin. Claude Code resolves scopes in a predictable order so overrides work intuitively.

## When to use it

- Project scope for team-wide integrations (CI, internal APIs).
- User scope for personal tools (your notes system, your calendar).
- Local scope for quick experiments.
- Plugin scope when shipping reusable MCP + skills bundles.

## Gotchas

- Project-scoped MCP config commits to the repo. Don't put secrets in it - use env var references.
- Conflicting scopes resolve by precedence. Read the doc if unexpected tools are loading.
- Plugin-scoped MCP may conflict with project-scoped ones. Namespace your tool names.

Official docs: https://code.claude.com/docs/en/mcp.md#mcp-installation-scopes


MCP Tool Search - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP tool search solves the "my MCP server has 80 tools" problem. Tools are loaded on demand instead of all at once.

## What it does

When a server has tool search enabled, Claude Code sees a searchable index rather than every tool loaded into context. The model queries the index when it needs a tool, loads the matching tool's schema, and calls it. You keep the expressive power of large tool suites without paying tokens for every tool, every turn.

## When to use it

- Any MCP server exposing more than a handful of tools.
- Multi-server setups where combined tool count bloats context.
- Cost-sensitive workflows where tool schemas were eating the budget.
- Large internal platforms with hundreds of operations.

## Gotchas

- Tool search adds a small latency for the first call to each tool.
- Search queries affect tool selection quality. Servers should provide good descriptions.
- Not every MCP server supports deferred loading yet - check the server docs.

Official docs: https://code.claude.com/docs/en/mcp.md#scale-with-mcp-tool-search


MCP OAuth - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP OAuth handles authentication for remote MCP servers without making you paste tokens by hand. Connect, authorize, and move on.

## What it does

When you add a remote MCP server that supports OAuth, Claude Code walks you through the authorization flow in your browser. Tokens land in the secure credential store and get refreshed automatically. You can pre-configure credentials for shared MCP servers or let each user authenticate dynamically.

## When to use it

- Remote MCP servers that manage user data (Gmail, calendar, CRM).
- Team deployments where individual auth is required.
- Any MCP server where a static API key isn't appropriate.
- Self-hosted MCP services that already speak OAuth.

## Gotchas

- Not every MCP server supports OAuth. Static tokens are the fallback.
- Expired tokens fail silently until Claude retries the flow. Watch for "unauthorized" errors.
- Different MCP servers have different scopes. Grant the narrowest scope that works.

Official docs: https://code.claude.com/docs/en/mcp.md#authenticate-with-remote-mcp-servers


MCP Resources - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP resources are read-only data exposed by MCP servers - docs, configurations, metadata - that Claude can reference and pull into context.

## What it does

A server exposes resources by URI. Claude can list them, read them, and cite them in responses. Unlike tools (which do things) and prompts (which templatize), resources are content you bring into the session. This is how MCP servers publish reference material without asking Claude to keep calling tools to fetch it.

## When to use it

- Surfacing internal documentation for Claude to reason over.
- Pulling configuration files from a config-as-service MCP.
- Listing available items from a catalog server.
- Making large, structured reference data available without custom tools.

## Gotchas

- Resources count against context when read. Watch the size.
- Not all servers expose resources - capabilities vary.
- Resource URIs aren't stable across server versions. Don't hard-code them in scripts.

Official docs: https://code.claude.com/docs/en/mcp.md#use-mcp-resources


MCP Prompts - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP prompts are reusable prompt templates an MCP server publishes. Claude Code surfaces them as slash commands so you can invoke them directly.

## What it does

A server declares a prompt with a name, description, and argument schema. Claude Code registers it as `/server:prompt` and the user can invoke it like any other command. The server gets to shape how the prompt expands - it can fetch data, interpolate arguments, and return a structured prompt body back to Claude.

## When to use it

- Shared team workflows encoded at the server level.
- Promoting common patterns as first-class commands.
- Integrating with specialized services that benefit from their own prompt shape.
- Centralizing prompt logic outside the client config.

## Gotchas

- Prompt collisions across servers need namespacing. Use the server prefix.
- Servers can change prompt behavior server-side - expectations drift.
- Treat MCP prompts like skills in terms of safety review.

Official docs: https://code.claude.com/docs/en/mcp.md#use-mcp-prompts-as-commands


MCP Channel Messaging - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

MCP channels let a server push messages into the session - deploy finished, alert fired, task completed - instead of waiting for Claude to poll.

## What it does

The server opens a channel with a name and topic. When events happen server-side, it sends messages into the Claude Code session. The model sees them as they arrive and can react in the current or next turn. This reverses the usual request-response flow and opens up real-time integrations.

## When to use it

- Long-running jobs where "tell me when done" is more efficient than polling.
- Alert and observability integrations that should surface in-session.
- Chat or collaboration bridges where messages arrive without being asked.
- Build/deploy dashboards that push status rather than expose an endpoint.

## Gotchas

- Channel messages interrupt the conversation flow. Noisy channels are distracting.
- Backpressure matters - a server that spams can wedge a session.
- Not every client supports channels yet. Check client compatibility when designing.

Official docs: https://code.claude.com/docs/en/mcp.md#push-messages-with-channels


Managed MCP - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Managed MCP lets admins define which MCP servers are permitted organization-wide. Individual users can only connect to servers the org has approved.

## What it does

Admins publish a managed configuration via the admin console. It lists allowed servers, denied servers, and defaults. Claude Code on managed devices respects the list - you can't add a blocked server, and the allowed ones may come pre-configured. It's how enterprises control the blast radius of MCP.

## When to use it

- Any organization using Claude Code at scale.
- Regulated industries where exfiltration risk matters.
- Teams standardizing on a specific MCP toolkit.
- Compliance scenarios where unauthorized MCP servers would violate policy.

## Gotchas

- Users can't work around managed MCP on their device. Escalations have to go through admins.
- Managed lists take precedence over user config. Local additions for blocked servers silently fail.
- Admins should document what's allowed and why - opaque deny lists frustrate everyone.

Official docs: https://code.claude.com/docs/en/mcp.md#managed-mcp-configuration


Agent Teams - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Agent Teams is the experimental multi-agent mode where several Claude Code instances work together with a shared task list and shared state.

## What it does

A team has a lead (coordinator) and teammates (workers). The lead decomposes the job, assigns tasks, and synthesizes results. Teammates claim tasks, work in parallel, and communicate directly when needed. You see their work in panes if you like. It's designed for jobs that genuinely benefit from parallelism - audits, broad refactors, large research.

## When to use it

- Tasks with many independent subtasks that can run in parallel.
- Codebase-wide audits or refactors.
- Research spanning many files or sources.
- Any time sequential delegation would waste wall-clock time.

## Gotchas

- Agent Teams is experimental. Expect rough edges and breaking changes.
- More agents means more cost. Measure the speedup versus the bill.
- Coordination overhead can swamp the benefit on small jobs. Use for genuinely parallel work.

Official docs: https://code.claude.com/docs/en/agent-teams.md


Team Lead - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The team lead is the coordinator agent in an Agent Teams setup. It decomposes the job, hands out tasks to teammates, and stitches the results into a coherent answer.

## What it does

The lead reads the user's goal, plans the decomposition, publishes tasks to the shared task list, and monitors progress. When teammates report back, the lead synthesizes findings, resolves conflicts, and returns the final result. It can also require plan approval before teammates execute.

## When to use it

- Any multi-agent run - every team has a lead by default.
- Complex jobs where a human doesn't want to manage the teammates directly.
- Tasks where synthesis is as hard as the underlying work.
- Patterns where one "lead + N workers" model is a clean fit.

## Gotchas

- A bad decomposition wastes everyone's turns. The lead's plan is load-bearing.
- Leads can become bottlenecks if they try to micromanage. Trust teammates with scope.
- The lead's synthesis is where quality wins or loses. Budget model strength accordingly.

Official docs: https://code.claude.com/docs/en/agent-teams.md#how-claude-starts-agent-teams


Shared Task List - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

The shared task list is the coordination primitive for Agent Teams. Teammates claim tasks, do them, and mark them complete - no direct dispatching required.

## What it does

The lead writes tasks to the shared list. Teammates watch the list, claim ones that match their skills, and post updates as they progress. Claims prevent double work. Statuses (pending, claimed, in-progress, completed, failed) make the team's state legible at a glance. It's the simplest coordination pattern that handles real parallelism.

## When to use it

- Any Agent Team run - the shared list is always present.
- Patterns where any teammate can do any task (fungible workers).
- Visibility - a human can watch the list and understand progress.
- Recovery - if a teammate stalls, another can re-claim.

## Gotchas

- Race conditions on claims are rare but possible. Watch for dual claims in logs.
- Tasks with unspoken dependencies cause deadlock. Use explicit task dependencies.
- Keep task descriptions actionable - vague tasks produce vague results.

Official docs: https://code.claude.com/docs/en/agent-teams.md#assign-and-claim-tasks


Inter-Agent Messaging - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Inter-agent messaging lets teammates talk to each other directly. The lead doesn't have to relay every question.

## What it does

Teammates can send messages to named peers or broadcast to the team. Messages appear in the recipient's context on the next turn. This is how a researcher can hand a finding to an implementer, or two implementers can sync on an interface, without funneling everything through the lead.

## When to use it

- Tasks that need a brief handoff between peers.
- Collaborative patterns where two agents share an interface contract.
- Reducing lead overhead on trivial coordination.
- Debugging - ask one agent to query another's state.

## Gotchas

- Messages add context to both sides. Keep them tight.
- Misuse can create tangled threads - prefer lead-mediated coordination for big decisions.
- Messaging is not a replacement for the shared task list. Tasks are the source of truth.

Official docs: https://code.claude.com/docs/en/agent-teams.md#context-and-communication


Split Pane Display - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Split pane display gives each agent team member its own terminal pane, so you can see what every teammate is doing at the same time.

## What it does

Claude Code launches a pane per teammate (tmux or iTerm2). Each pane shows that agent's live output, tool calls, and status. You watch the team collaborate in real time instead of reading a combined log stream. The lead's pane typically sits at the top.

## When to use it

- Demos and recordings where "look at the team working" is the point.
- Debugging a team run when you need to see per-agent state.
- Understanding how work actually distributes in practice.
- Teaching others what multi-agent orchestration looks like.

## Gotchas

- Lots of panes on a small screen become unreadable. Cap teammates or switch to summary mode.
- tmux-style panes require a tmux session. iTerm2 panes need iTerm2.
- Output can scroll fast. Record the session if you want to review later.

Official docs: https://code.claude.com/docs/en/agent-teams.md#choose-a-display-mode


Plan Approval - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Plan approval is a gate in Agent Teams where teammates must present a plan to the lead (or the user) before doing any real work.

## What it does

When plan approval is on, teammates enter plan mode on claim. They produce a plan explaining their intended steps. The lead reviews, either approves the plan or sends it back for revision. Only then does the teammate execute. It's the safety net for teams working on large or sensitive changes.

## When to use it

- Large refactors where wrong execution is expensive to undo.
- Multi-agent jobs on critical infrastructure.
- Any run where you want the lead to catch bad decompositions before they cost turns.
- Teaching a multi-agent workflow while keeping guardrails on.

## Gotchas

- Approval adds latency. Don't use it for fast exploratory tasks.
- A careless lead rubber-stamps bad plans. Quality depends on the lead's attention.
- Too many revisions can stall a team. Set a revision cap.

Official docs: https://code.claude.com/docs/en/agent-teams.md#require-plan-approval-for-teammates


Task Dependencies - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Task dependencies let you express "don't start B until A finishes" in the shared task list. Pending tasks wait, then unblock.

## What it does

When you create a task, you can list other task IDs it depends on. The shared task list tracks the graph. Dependent tasks stay in a waiting state until every prerequisite completes successfully. Once they do, the task becomes claimable and teammates can pick it up.

## When to use it

- Multi-step work where order matters (migration step 1 before step 2).
- Producer/consumer patterns (one teammate generates, another reviews).
- Preventing teammates from racing into half-done work.
- Encoding checklist-style workflows in a team.

## Gotchas

- Cycles in dependencies deadlock the team. Validate before publishing tasks.
- Failed prerequisites block dependents forever unless you handle failures explicitly.
- Very deep dependency chains serialize work that could run in parallel. Shallow trees beat deep ones.

Official docs: https://code.claude.com/docs/en/agent-teams.md#assign-and-claim-tasks


Subagent Definitions as Teammates - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Custom subagent definitions plug directly into Agent Teams. Your "reviewer", "migrator", or "doc writer" subagents become teammates without rewriting them.

## What it does

When a team spins up, you can pass a list of subagent definitions for the lead to use as teammates. The lead picks the right agent for each task based on descriptions and tool allowlists. This gives you specialized team compositions - e.g. one coder, one reviewer, one tester - without custom team wiring.

## When to use it

- Composing teams of roles you already use as subagents.
- Enforcing tool boundaries within a team (reviewer has no write access).
- Consistency - the same agent definition behaves the same as a teammate or a standalone delegation.
- Sharing team compositions across projects via repo-level definitions.

## Gotchas

- A poor mix of roles produces poor team results. Think about coverage.
- Subagents designed for single-task isolation may not fit team workflows that need messaging.
- Frontmatter changes to the subagent definition apply to the team on next spawn.

Official docs: https://code.claude.com/docs/en/agent-teams.md#use-subagent-definitions-for-teammates


/loop Command - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

`/loop` is the simplest way to make Claude do the same thing over and over - poll for status, re-run a check, keep monitoring an endpoint.

## What it does

Run `/loop  ` and Claude re-executes the prompt on that cadence. Omit the interval and Claude picks a sensible pace based on the task. You can stop the loop at any time. Common patterns: watch a deploy, re-run tests, check for new emails.

## When to use it

- Polling status pages, health endpoints, or CI jobs.
- Recurring checks on a long-running process.
- Keeping a dashboard-like view running in a terminal.
- Dev workflows where "keep checking until X" is the shape of the work.

## Gotchas

- Loops burn tokens on every iteration. Set a sensible interval and a stop condition.
- One-off tasks don't benefit from loops - use them only for genuinely recurring work.
- Loops stop when the session ends. For durable scheduling, use routines or scheduled tasks.

Official docs: https://code.claude.com/docs/en/scheduled-tasks.md#run-a-prompt-repeatedly-with-loop


Scheduled Tasks (Desktop) - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Scheduled tasks in the Claude desktop app let you set up recurring work via a GUI. Pick a cadence, write a prompt, and Claude runs it on schedule.

## What it does

The desktop app exposes a scheduler UI. You set a name, a schedule (interval or cron), a target project, and a prompt. Claude fires the task on time, runs it, and surfaces the result. You can view history, edit, or disable tasks from the same UI.

## When to use it

- Daily triage, audits, or summaries that run on your machine.
- Personal workflows where cloud routines would be overkill.
- Tasks that need access to your local files and tools.
- Any recurring prompt you'd otherwise set a reminder for.

## Gotchas

- Your machine has to be awake (or wake) for the task to fire. Laptops asleep won't run it.
- Long-running tasks can collide with your interactive work. Schedule off-hours.
- Scheduled tasks respect the project's permission rules. A denied tool silently fails.

Official docs: https://code.claude.com/docs/en/desktop-scheduled-tasks.md


Routines (Web) - Claude Code
Developers Digest — Thu, 23 Apr 2026 00:00:00 GMT

Routines are cloud-hosted scheduled Claude Code jobs. Unlike desktop scheduled tasks, they run on Anthropic infrastructure and don't need your machine to be on.

## What it does

You define a routine with a schedule, a trigger (schedule, API webhook, or GitHub event), a connected repo, and a prompt. Anthropic runs the routine in a cloud environment, executes the prompt with full Claude Code capabilities, and pushes results back (to a PR, an API response, a notification). This is how you automate Claude work that has to happen even when you're offline.

## When to use it

- Nightly triage, release note generation, or dependency updates.
- GitHub-triggered automation (run on every PR, every push to main).
- API-triggered jobs from external systems.
- Team automations where no single person's laptop should be the linchpin.

## Gotchas

- Routines run without a human watching. Make outputs fail loudly when something goes wrong.
- Cloud routines can't reach your local filesystem. The target has to be a connected repo.
- Pricing is usage-based - a runaway routine can rack up spend fast. Set caps.

Official docs: https://code.claude.com/docs/en/routines.md


AI Design Slop: 15 Patterns That Out Your App as Vibe-Coded
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## The visual fingerprint of a Claude-generated landing page

If you have been browsing Show HN for the past six months you have felt this without being able to name it. The pages look fine. They are coherent. They are polished. And they all somehow look like the same page.

Adrian Krebs gave the feeling a name and a measurement. His [Scoring Show HN submissions for AI design patterns](https://www.adriankrebs.ch/blog/design-slop/) sits near the top of HN tonight at 277 points and 205 comments. He ran 500 of the latest Show HN landing pages through Playwright, scored each one against fifteen DOM and CSS patterns that designers he talked to described as tells, and binned the results.

The numbers:

- **21%** of pages were heavy slop, triggering five or more of the fifteen patterns.
- **46%** were mild, triggering two to four patterns.
- **33%** were clean, zero or one pattern.

Two-thirds of what you see on Show HN right now has a visual fingerprint that says "generated by a chat interface without an opinion." That is a lot. It is also why the Show HN stream has started to feel samey. The generator is the same. The defaults leak through.

## The 15 patterns

Krebs grouped the tells into four buckets. This is the full list, because if you are shipping with [Claude Code](/blog/what-is-claude-code-complete-guide-2026) or Cursor right now, this is the checklist you should be running your own landing page against.

### Fonts

1. Inter used for everything, especially the centered hero headline
2. Space Grotesk, Instrument Serif, or Geist Serif italic used as the accent font for one hero word in an otherwise-Inter page

Inter is a wonderful typeface. It has also become the Helvetica of the LLM era. Every generated landing page defaults to it unless you specifically ask for something else. If you want to stand out, start by not using Inter.

### Colors

3. "VibeCode Purple" - a specific shade of lavender-purple that leaks out of most image generation and a lot of text-to-landing-page prompts
4. Permanent dark mode with medium-grey body text and all-caps section labels
5. Barely-passing body-text contrast in dark themes
6. Gradients everywhere
7. Large colored glows and colored box-shadows

Dark mode with purple accents is the default aesthetic the LLMs reach for when you do not specify one. It feels "modern" in a way that is so universal it has become invisible. The contrast issue is the biggest functional problem - generated dark themes routinely ship body text that fails WCAG AA.

### Layout quirks

8. Centered hero set in a generic sans
9. Badge positioned right above the hero H1
10. Colored borders on cards, usually on the top or left edge
11. Identical feature cards with an icon on top
12. Numbered "1, 2, 3" step sequences
13. Stat banner rows
14. Sidebar or nav with emoji icons
15. All-caps headings and section labels

The colored-left-border card is the most specific tell in the list. A designer Krebs quoted said "colored left borders are almost as reliable a sign of AI-generated design as em-dashes for text." Once you notice it you cannot stop noticing it.

### CSS patterns

The two dominant CSS fingerprints are shadcn/ui defaults and glassmorphism. shadcn in particular is a library that is explicitly designed to be copy-pasted by [AI agents](/blog/ai-agents-explained), which means every AI-generated landing page without stylistic intervention converges on the shadcn visual. Glassmorphism is the frosted-glass card treatment that had a moment in 2022 and has been the LLM default ever since.

## The method is worth stealing

The part of Krebs' write-up I want to highlight is the scoring method. It is cheap, reproducible, and something you could run against your own site this afternoon.

- Playwright loads each page in a headless browser.
- A small in-page script walks the DOM and reads computed styles.
- Every pattern is a deterministic CSS or DOM check. No LLM judge looking at screenshots.

The last point is important. Letting an LLM grade AI slop by eye would introduce the exact bias you are trying to measure. Deterministic checks against computed styles take the LLM out of the scoring loop. Krebs reports 5-10 percent false positives on manual QA, which is tolerable for bucketing.

If you want to adapt this for your own internal use, the checklist is small enough to implement in a few hours. Write fifteen functions that each answer "does this page trigger this pattern." Run them against your homepage, your pricing page, your docs. Bucket the result. Decide where you want to be. The [AI coding tools pricing](/blog/ai-coding-tools-pricing-2026) cluster is a good example because comparison pages need both clarity and restraint.

## Why it matters when you are shipping

A few counter-arguments to head off before they come up.

**"But my landing page works."** Yes. That is Krebs' read too. He explicitly says AI design slop is not bad, just uninspired. Validating a business was never about fancy design. The pre-LLM equivalent was everyone using Bootstrap. The practical failure mode is not that slop pages do not convert, it is that they stop standing out in a sea of identical slop pages. Differentiation gets more expensive, not less, as the defaults improve.

**"I care about shipping, not design."** Then ship ugly on purpose rather than ship slop by accident. An ugly page with a clear point of view is more memorable than a generic page with no point of view. If you are resource-constrained, the cheapest way to stand out is to pick a single strong opinion (a loud color, a bold type choice, an uncommon layout) and commit to it. A slop page is the expensive option, because it uses up design budget without giving you distinctive assets at the end.

**"This is just taste-gatekeeping."** It is and it isn't. The patterns on Krebs' list are measurable. They are the output of a generator with known biases. Noticing them and making deliberate choices against them is not gatekeeping, it is taste calibration in an era where the default aesthetic is being mass-produced. You can still choose shadcn and a purple accent. Just do it because you want to, not because that is what the model gave you.

## What the clean 33% are doing

Krebs does not go deep on what separates the clean third from the slop-heavy fifth, but the pattern is consistent across sites I have audited with the same checklist. Clean sites do three things.

**They pick a color palette that is not the LLM default.** Warm earth tones, or high-contrast black-and-a-single-bright, or a Gumroad-ish cream-and-pink, or a Stripe-ish grey-and-blue. Anything with a point of view. Explicitly not the default lavender.

**They pick a type system that is not Inter.** Geist, Haas Grotesk, Untitled Sans, Söhne, Inktrap, Migra, anything else. Pair it with a body font that is not also Inter. The contrast wakes the page up.

**They use one strong layout primitive and repeat it.** Not seven feature cards with seven different icon treatments. Not three stat banners and four step sequences and a sidebar with emojis. One primitive, repeated until it becomes the site's visual signature. This is the single highest-leverage discipline on the list.

## The tool you can build this weekend

Krebs teased a potential open source of the scoring code and said "let me know if there is interest." This is worth asking for. A small CLI that runs a Playwright scoring pass over any URL and returns a slop score is a useful piece of infrastructure. It belongs next to Lighthouse in the pre-launch checklist.

If he ships it, great. If he does not, it is a weekend project for someone else to build. The primitives exist. The scoring rubric is public. The market is every single developer who just shipped a landing page this week with [Cursor](/blog/what-is-cursor-ai-code-editor-2026) and is wondering if the reason their launch tweet fell flat is that they accidentally shipped slop.

Put differently: you can now measure the visual output of your AI stack against a fifteen-item checklist. The measurement is cheap. The fix is mostly just making deliberate choices. That is a better loop than hoping your design instincts have survived a year of chat-interface defaults.

## Read the original

The full essay with screenshots is at [adriankrebs.ch/blog/design-slop](https://www.adriankrebs.ch/blog/design-slop/). It takes ten minutes and it will permanently change how you read a Show HN stream.

## FAQ

### What is AI design slop?

AI design slop refers to the visual patterns and aesthetic choices that AI tools like Claude, Cursor, and v0 default to when generating landing pages and web interfaces. These patterns are not bad individually, but they have become so common that they create a samey, uninspired look across AI-generated sites. The term comes from "vibe coding" culture where developers ship quickly without strong design opinions, letting the AI defaults leak through.

### How do I know if my landing page has AI design slop?

Run your page against the 15-pattern checklist: Inter font everywhere, Space Grotesk or Geist Serif italics for accent words, lavender-purple accents, dark mode with low-contrast body text, gradients and glows, centered hero with badge above the H1, colored left borders on cards, identical feature cards with icons, numbered step sequences, stat banners, sidebar with emoji icons, and all-caps section labels. If you trigger five or more patterns, your page is in the heavy slop category.

### Is AI design slop actually bad for conversions?

Not necessarily. Adrian Krebs' research explicitly notes that slop pages are not bad, just uninspired. They can still convert fine. The problem is differentiation - when two-thirds of Show HN pages look identical, standing out becomes harder. The practical failure mode is not that slop pages do not work, it is that they no longer create memorable brand impressions in a sea of similar pages.

### How do I avoid AI design slop when using Claude Code or Cursor?

Make three deliberate choices before generating: pick a color palette that is not the default lavender (try earth tones, cream-and-pink, or high-contrast black-and-bright), use a typeface that is not Inter (Geist, Söhne, Untitled Sans), and commit to one strong layout primitive repeated throughout rather than multiple card styles and section types. Feed these constraints to your AI tool in your system prompt or CLAUDE.md file.

### What fonts should I use instead of Inter?

For sans-serif alternatives that signal intentionality: Geist, Haas Grotesk, Untitled Sans, Söhne, or Inktrap. For serif options: Tiempos, GT Sectra, or Freight Text. The goal is not to avoid Inter because it is bad - it is an excellent typeface - but to make a deliberate choice rather than accepting the default. Pair your headline font with a distinct body font for additional differentiation.

### What is the "colored left border" AI design pattern?

The colored left border card is one of the most reliable AI design tells. It appears as a card or blockquote with a 3-4px colored stripe on the left edge, usually in purple, blue, or a gradient. Designers have described it as "almost as reliable a sign of AI-generated design as em-dashes are for AI-generated text." Once you notice it, you will see it on nearly every AI-generated landing page.

### Can I use shadcn/ui without creating AI design slop?

Yes, but it requires intentional customization. shadcn is explicitly designed to be copy-pasted by AI agents, which is why the library's defaults show up in so much AI-generated output. To avoid the samey look: customize the color tokens, adjust the border radius values, modify the shadow depths, and pick non-default variants for components. The library is meant to be a starting point for customization, not a finished design system.

### How do I measure AI design slop programmatically?

Use Playwright to load your page in a headless browser, run in-page scripts that walk the DOM and read computed styles, and check against the 15 patterns with deterministic CSS and DOM queries. No LLM judge needed - that would introduce the bias you are trying to measure. Adrian Krebs reports 5-10% false positives with this method, which is acceptable for bucketing scores into clean, mild, or heavy slop categories.

## Further reading

- [Zed's Parallel Agents: The Editor Catches Up](/blog/zed-parallel-agents-first-editor-making-it-native)
- [Over-Editing: Why Your AI Agent Rewrites What Isn't Broken](/blog/over-editing-when-ai-rewrites-what-isnt-broken)
- [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026)

## Related apps

- [Subagent Studio](https://developersdigest.tech/blog/ten-tools-for-agent-infrastructure) - Visual designer for Claude Code subagent definitions. Build, test, and export configs.
- [Agent Hub](https://agenthub.developersdigest.tech) - One control panel for Claude Code, Codex, Gemini, Cursor, and 10+ AI coding harnesses. Desktop app for Mac.

## Related

- [Subscribe to DevDigest on YouTube](https://www.youtube.com/@DevelopersDigest?sub_confirmation=1) for hands-on walkthroughs


Codeburn: The First TUI That Actually Shows Where Your Claude Max Subscription Is Going
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## Source links

This page is grounded in the public [Codeburn GitHub repo](https://github.com/getagentseal/codeburn), [Anthropic pricing](https://www.anthropic.com/pricing), [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code), and [Cursor pricing](https://cursor.com/pricing). For broader tool budgeting, use the [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026) and the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison).

If you are evaluating which tool to pay for next:

- Start with the [pricing hub](/pricing) and the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison).
- If you are choosing between major coding agents, use the [comparison hub](/compare).

## The question Claude Max does not answer

If you are on a Claude Max subscription, you have a cap and a usage bar. What you do not have is a breakdown. You cannot see which project ate the most tokens this week, which agent loop ran hot at 2am, or how many dollars of inference you would have paid for if you were on pay-as-you-go. The bar just creeps toward full and then resets.

[Codeburn](https://github.com/getagentseal/codeburn) from Agent Seal is the first tool that tries to answer that question directly. It is a terminal UI that reads the local session logs from Claude Code and Cursor and renders them as a live dashboard of token spend, cost estimates, and per-project breakdowns. The repo hit 3,400+ stars in its first week on GitHub. That kind of number is usually a sign that a tool landed on a real, widely felt pain point.

This post is a look at what codeburn actually does, where the data comes from, and why it is suddenly the one tool a lot of [Claude Code](/blog/what-is-claude-code-complete-guide-2026) users wish they had installed three months ago.

## What codeburn shows you

Codeburn is a TUI, meaning it runs inside your terminal and renders panels of data that update as you work. It is not a hosted dashboard. There is no account, no login, no telemetry leaving your machine. It parses the session and usage files that Claude Code and [Cursor](/blog/what-is-cursor-ai-code-editor-2026) already write to your local disk and surfaces them as one coherent view.

The main panels are:

- **Token spend by model.** Sonnet versus Opus versus Haiku, broken down by input, output, cache read, and cache write tokens. If you have ever wondered whether your agent is actually hitting the cache the way you hoped, this is the first place you can see it.
- **Cost estimate in dollars.** Codeburn applies [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s published per-token rates to your session data and tells you what the equivalent pay-as-you-go bill would have been. On a Max plan you do not pay that number. But seeing it is clarifying. It turns an abstract usage bar into a concrete receipt.
- **Per-project and per-session breakdowns.** Which repo burned the most tokens this week? Which session was the most expensive? Which day of the month is your heaviest? The TUI lets you filter and sort.
- **Cursor usage alongside Claude Code.** If you use both, codeburn merges them into one view. That alone is a small win if you have been juggling two separate mental budgets.

None of this data is new. It has always been sitting on your disk. Codeburn is the first tool to make reading it trivial.

## Why this tool landed so hard

A week-one star count in the thousands is rare. It usually means the maintainer either has a large audience already, or the tool solves a problem that a lot of people were actively Googling for. Codeburn is closer to the second case. The Claude Code subreddit and developer Twitter have been full of "where is my Max subscription actually going" posts for months. Anthropic's usage page shows you a bar. It does not show you the breakdown.

There is a second reason codeburn resonates, and it connects directly to [the over-editing essay](/blog/over-editing-when-ai-rewrites-what-isnt-broken) that is making the rounds right now. When models make fifty-line diffs for one-character bugs, every one of those extra lines is tokens. When an agent loops on a test that is failing for environmental reasons and re-reads the same files twenty times, that is tokens. When Claude Code opens a file you did not ask it to open because it wants to "understand the context," that is tokens.

The over-editing post mentions "$50 of tokens burned" on what should have been a one-line fix. That number is not theoretical. It is exactly the kind of number codeburn is built to surface. Before codeburn, you could feel that a session went long. You could not point at a line item that said "this project, this day, this model, this many dollars." Now you can.

## What codeburn is not

Worth being honest about the limits.

Codeburn is a viewer, not a controller. It does not stop a runaway session, throttle your agent, or alert you when you cross a threshold. If Claude Code is in a loop at 3am, codeburn will show you the damage after the fact. It will not intervene. That is a feature a competing tool or a future version could add, but it is not here today.

Codeburn also relies on the structure of local log files that Anthropic and Cursor can change without notice. If either vendor reorganizes their session format, the tool will need an update to keep parsing correctly. This is the usual tradeoff for any tool built on top of logs it does not own. The project is active enough that this will probably get fixed quickly when it happens, but it is a real dependency.

Cost estimates are also exactly that: estimates. Anthropic's per-token rates can change, and the tool needs to keep up. The dollar numbers codeburn shows are useful as signal, not as an audit.

## Who should install it

If you have a Claude Max subscription and you have ever wondered where the hours went, the answer is yes. Install it. The feedback loop of seeing your spend in a TUI next to your editor is small in effort and large in payoff. You start noticing which kinds of prompts are cheap and which are expensive. You start noticing when an agent goes off the rails and eats ten thousand tokens re-reading the same three files. Awareness is the first step toward changing the behavior.

If you are on a team, the case is stronger. Shared projects with multiple engineers using Claude Code benefit from the per-project view. You can see which repos are heavy users, which are efficient, and have a concrete starting point for a conversation about agent discipline.

If you are pay-as-you-go, codeburn is closer to necessary. The cost panel is not a what-if anymore. It is the actual invoice forming in real time.

## The bigger pattern

What codeburn represents is worth naming. We are moving from the era of "[AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026) exist" into the era of "AI coding tools have an observability problem." Models are fast. Models loop. Models over-edit. Models read files they do not need to read. All of this shows up on your token bill, and for a long time the bill has been a black box.

Tools like codeburn are the first wave of making that box transparent. The next wave will probably be alerting, throttling, and policy. Team admins will want to set budgets per project. Solo developers will want a hard stop when a session crosses a threshold. The building blocks are the same log files codeburn is already reading.

For now, install it. Watch the numbers for a week. You will learn more about your own workflow than any productivity article can teach you.

Codeburn is on GitHub at [github.com/getagentseal/codeburn](https://github.com/getagentseal/codeburn).

## FAQ

### What is Codeburn?

Codeburn is an open-source terminal UI (TUI) dashboard that reads local session logs from Claude Code and Cursor to display token usage, cost estimates, and per-project breakdowns. It runs entirely on your machine with no external telemetry.

### Does Codeburn work with Claude Max subscriptions?

Yes. Codeburn parses the same usage data Claude Code writes locally regardless of your subscription tier. On Max, the cost panel shows what you would have paid at pay-as-you-go rates - useful for understanding which projects burn the most tokens.

### Can Codeburn stop a runaway Claude Code session?

No. Codeburn is a viewer, not a controller. It shows you the damage after the fact but does not throttle or alert during a session. That feature may come in a future version or competing tool.

### Does Codeburn support Cursor alongside Claude Code?

Yes. Codeburn merges usage data from both Claude Code and Cursor into a single dashboard view. If you use both tools, you get one unified picture of your token spend.

### Is the cost estimate Codeburn shows accurate?

It is an estimate based on Anthropic's published per-token rates. It is not an invoice. Rates can change, and the tool needs updates to stay current. Treat the dollar numbers as directional signal, not as audit-grade accounting.

### Do I need an account or login to use Codeburn?

No. Codeburn is fully local. It reads log files from your disk and renders them in the terminal. There is no hosted service, no account, and no data leaving your machine.

### Will Codeburn break if Anthropic changes their log format?

Possibly. Codeburn depends on the structure of local session files that Anthropic controls. If the format changes, the tool will need an update. The project is actively maintained, so fixes typically land quickly.

### Is Codeburn useful for teams?

Yes. The per-project view lets teams see which repositories are heavy consumers, which sessions were expensive, and opens a concrete conversation about agent discipline and cost awareness.

If Codeburn is part of your tool-selection process, read these next:

- [Pricing hub](/pricing)
- [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026)
- [Claude Code usage limits playbook](/blog/claude-code-usage-limits-playbook-2026)
- [Claude Code vs Cursor (side-by-side)](/compare/claude-code-vs-cursor)
- [Claude Code vs Codex (side-by-side)](/compare/claude-code-vs-codex)


Intent Debt: The AI-Era Debt Nobody Is Tracking
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## Technical debt is in the code. Cognitive debt is in your head. Intent debt is in the artifacts.

Martin Fowler published a short fragment on April 2 that is quietly the most important framing I have read on AI-era software engineering this quarter. The HN thread is sitting at 192 points and 46 comments as I write this, and the conversation under it is the kind of conversation every team shipping with [coding agents](/blog/what-is-an-ai-coding-agent-2026) needs to be having out loud.

The core idea comes from Margaret-Anne Storey, which Fowler summarizes. System health is not a single axis. It is three layers. Each one can fall behind independently. Each one has a different remediation path. And if you are only tracking the first one, you are flying blind on the other two.

### Technical debt lives in code

The original definition, unchanged. It accumulates when implementation decisions compromise future changeability. Shortcut here, duplicated helper there, stringly-typed API that grows three dialects over six months. Tech debt limits how the system can change.

Tech debt is the easy one to see. You can grep for it. You can measure it with linters, cyclomatic complexity, duplication percentage, and the smell-of-the-week. Every engineering team in the world has a shared language for this kind of debt.

### Cognitive debt lives in people

This is the one the AI discourse has already latched onto. It accumulates when shared understanding of the system erodes faster than it is replenished. Cognitive debt limits how teams can reason about change.

A team can have perfectly clean code and still carry crushing cognitive debt. Someone wrote the module six months ago, shipped it, left the company. The tests pass. The code is tidy. Nobody left on the team understands why the retry logic uses exponential backoff with jitter rather than a fixed interval. Cognitive debt is the gap between "the code works" and "the team can still explain why it works."

[AI agents](/blog/ai-agents-explained) accelerate cognitive debt. They generate code that nobody on the team has held in their head. Even when the code is good, the act of writing is what builds comprehension, and skipping that act skips the comprehension.

### Intent debt lives in artifacts

Here is the new one. It accumulates when the goals and constraints that should guide the system are poorly captured or maintained. Intent debt limits whether the system continues to reflect what we meant to build. And critically for the AI era, it limits how humans and AI agents can continue to evolve the system effectively.

Read that second sentence again. Intent debt is the debt that directly throttles how well an agent can work on your codebase.

Your `CLAUDE.md` is an intent artifact. Your `AGENTS.md` is an intent artifact. Your ADRs, your design docs, your acceptance criteria, your README, your README's "non-goals" section, your issue templates, your `docs/` folder, your internal glossary - all intent artifacts. When the code drifts away from the intent and nobody updates the artifact, intent debt accumulates. When no intent artifact ever existed, intent debt is maximal by default.

## Why this framing matters right now

The reason the three-layer model lands differently in 2026 than it would have in 2019 is AI agents. The agent cannot read your mind. It cannot recover tacit knowledge. It cannot infer unwritten constraints. The agent reads whatever artifacts you wrote down. If those artifacts do not match what you actually meant, the agent confidently implements the documented wrong thing.

Intent debt used to be a soft cost. A new hire ramped slower. A PM asked a question that should not have needed asking. The system eventually absorbed the knowledge back through tribal repetition. In the agent era, intent debt is a direct throughput cost on every single agent run. Every ambiguous spec, every stale ADR, every missing constraint document compounds across every future iteration.

Fowler cites a recent paper from Shaw and Nave at Wharton that extends Kahneman's two-system model by adding AI as System 3. The paper introduces a distinction I have been chewing on since I read the fragment.

- **Cognitive offloading** is strategic delegation of thinking during deliberation. You use the agent as leverage, you stay in the loop, you verify.
- **Cognitive surrender** is uncritical reliance on externally generated reasoning. You outsource the thinking, you exit the loop, you trust.

Intent debt is the mechanism that turns offloading into surrender. When the artifacts do not capture intent, the agent has nothing to check its own work against. The human reviewer also has nothing to check it against. Both parties shrug at the diff and merge it. Surrender by omission.

## Diagnosing intent debt on your own project

Here are five quick checks I would run today against any repo that AI agents touch.

First, the five-minute test. Open the repo fresh. Can you, inside five minutes, articulate what this system is for, what it is not for, and the three hardest constraints that shape every decision in it? If the answer is no, intent debt is present at the architecture layer.

Second, the agent prompt test. Open your `CLAUDE.md` or `AGENTS.md`. Is it a working document you have updated in the last thirty days, or is it a stub that was written once and abandoned? Stale agent config is pure intent debt.

Third, the non-goals test. Find your most recent README. Does it have a non-goals section? A description of what the system will not do, by design, even if it looks like a natural extension? Systems without documented non-goals accumulate the worst kind of intent debt because they get constantly extended into shapes the original authors would have rejected.

Fourth, the ADR test. Walk the last ten material commits. Is there an Architectural Decision Record, a PR description, or a linked issue that explains the *why* behind each material choice? Or is the history a stream of "update thing" commits? Commits without captured reasoning are intent debt being generated in real time.

Fifth, the ubiquitous language test. Ask three teammates to define the three most important domain terms in the codebase. Do the definitions match? If they drift, your code has drifted too, because the terms are the hooks the code hangs on. Fowler quotes Unmesh on this point directly: good names cut through complexity and turn code into a schematic everyone can follow. Drifted names are intent debt made visible.

## What to do about it

Fix intent debt with artifacts, not with meetings. The meetings dissolve. The artifacts persist and the agent can read them.

- **Write the `CLAUDE.md` or `AGENTS.md` before the first agent run, not after.** Capture what the system is, what it is not, the tone of the codebase, the constraints that must be respected, and the commands the agent should know about. This is the single highest-leverage intent artifact you can create.
- **Write ADRs cheaply and aggressively.** One page. Why this decision, what we rejected, what we would revisit. Three sentences beats nothing. Your future agent will cite them.
- **Add a non-goals section to every README.** The things the system will not do are often more important to an agent than the things it will do. Agents love to add features you rejected on purpose.
- **Update the intent artifact in the same PR that breaks the intent.** If the commit changes what the system means, the artifact that describes the meaning has to change in the same commit. This is the single best discipline for keeping intent debt from accumulating invisibly.
- **Make intent artifacts executable where you can.** A failing test codifies intent better than a paragraph. A type system codifies intent better than a comment. A linter rule codifies intent better than a code review. Executable intent does not rot because CI enforces it.

## The second-order argument

Fowler also quotes Ajey Gore in the same fragment, making an argument that deserves its own post but is worth surfacing here. If coding agents make the writing of code cheap, the expensive thing becomes verification. What does "correct" mean. What does "good enough" look like. Which edge cases matter and which do not.

Gore takes this all the way to the org chart. He argues the team that used to have ten engineers building features now has three engineers and seven people defining acceptance criteria, designing test harnesses, and monitoring outcomes. The uncomfortable demotion is of the act of building and the promotion is of the act of judging.

Read that in the intent-debt frame. Acceptance criteria are intent artifacts. Test harnesses are executable intent. Monitoring outcomes is intent verification at runtime. The whole shift Gore describes is a shift from producing code to producing intent.

That is the direction the craft is moving. The teams that invest in intent artifacts now will have agents that can run faster, on longer tasks, with fewer reviews, and with fewer regressions. The teams that treat `CLAUDE.md` as a one-time setup will watch the gap widen every week.

## The honest bit

I do not think Fowler has fully landed the argument yet. The fragment is brief by design. The framework is Margaret-Anne Storey's. The experimental backing from Shaw and Nave is still lab-stage. The three-debt taxonomy will probably get refined, maybe renamed, maybe absorbed into something broader. Debt metaphors proliferate, as Fowler himself notes with visible fatigue.

But the direction is right. The second layer, cognitive debt, has already become common vocabulary in the agent discourse. The third layer, intent debt, has not. It deserves to. It is the layer that most directly determines whether your agent stack compounds or decays.

Read the [original fragment](https://martinfowler.com/fragments/2026-04-02.html). It is a fast twenty minutes. Then open your repo and look at your `CLAUDE.md`.

## Further reading

- [Over-Editing: Why Your AI Coding Agent Rewrites What Isn't Broken](/blog/over-editing-when-ai-rewrites-what-isnt-broken) - the flip side of the cognitive-surrender problem
- [AI-Native Development Workflow](/blog/ai-native-development-workflow)
- [How to Write CLAUDE.md: The Complete Guide](/blog/how-to-write-claudemd-the-complete-guide) - the single highest-leverage intent artifact


Over-Editing: Why Your AI Coding Agent Rewrites What Isn't Broken
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## The bug you asked to fix is one line. The diff is fifty.

If you have spent any time with Claude Code, Cursor, Codex, or [GitHub Copilot](/blog/github-copilot-coding-agent-cli-2026) in the past year, you have lived this moment. You point the agent at a simple off-by-one. You ask for the minimal fix. The bug gets fixed. And then you scroll the diff and half the function is gone. A helper you did not request has appeared. A variable has been renamed because the model thought the new name was clearer. Input validation has been bolted onto a path that never needed it. The whole shape of the function has changed.

A new essay from [nrehiew](https://nrehiew.github.io/blog/minimal_editing/) gives this failure mode a name and a measurement. The title is "Coding Models Are Doing Too Much." The subtitle is blunt: "Don't rewrite what isn't broken." It is sitting near the top of Hacker News as I write this, with 290 points and 172 comments in the first few hours. The discussion it has kicked off is one that every team shipping with AI agents needs to have.

## What over-editing actually is

The author defines over-editing precisely: a model is over-editing if its output is functionally correct but structurally diverges from the original code more than the minimal fix requires.

The demonstration example is brutal. The bug is a single off-by-one: `range(len(x) - 1)` should be `range(len(x))`. The minimal fix is one character. GPT-5.4 with high reasoning effort responds by rewriting the entire function. It adds `None` checks that nobody asked for. It converts arrays with `np.asarray` and explicit `dtype=float`. It adds finite-value masking. It validates array sizes. It changes the signature of the `curve_fit` call. It replaces the plotting logic entirely. The output passes the tests. The output is a disaster to review.

This is the kind of failure that tests cannot catch. If the code is functionally correct, every green check still turns green. Pass@1 stays at 100 percent. The reviewer is the only line of defense, and the reviewer is now staring at fifty changed lines trying to figure out which one fixed the bug and which forty-nine are new surface area to audit.

## Why tests cannot save you

The default advice for working with [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026) is "just write more tests." The logic is that if your tests are good enough, the model cannot ship anything broken past them. That advice is correct but incomplete.

Over-editing is a brown-field failure. The existing code was already understood, was already written the way it was for reasons the team chose deliberately, and was already part of the codebase's shape. The model's job was to fix the bug and nothing else. Instead it made fifty decisions the team did not make and signed your name to them.

Tests verify correctness. They do not verify restraint. They cannot tell you whether the model respected the shape of your code. They cannot tell you whether a refactor snuck in under the cover of a bug fix. They cannot tell you whether the variable names drifted. That verification has to happen in code review, which is already the bottleneck on most teams, and which over-editing makes dramatically more expensive.

## Why models do it

There are three plausible explanations, and my read is that all three are happening at once.

First, training incentive. Most RLHF and preference data rewards thorough, helpful-looking answers. A diff that adds validation, handles edge cases, and improves the function feels more effortful than a one-character change. Annotators give it higher marks. The model learns that big diffs win.

Second, reasoning models are worse. The author calls this out directly. High-reasoning-effort settings make the over-editing problem worse, not better. The model reasons its way into additional changes that feel defensible in chain-of-thought but that were never requested. Reasoning without constraint is expansion without permission.

Third, context loss. Models do not always fully load the context of what the existing code is doing before editing. They regenerate the function from scratch, approximating it, and then merge their approximation back. What looks like a targeted edit is actually a regeneration with drift baked in.

None of those causes go away on their own. The open question is whether we can train for restraint.

## What the research actually measures

The experimental setup is a clean piece of work. Rather than using another LLM to introduce bugs, the author programmatically corrupts 400 problems from BigCodeBench. Corruptions are tiny and mechanical: flipping `<` to `<=`, swapping `+` for `-`, changing `True` to `False`. Each corrupted sample remains syntactically valid and is verified to break the corresponding test cases. The ground-truth edit is therefore exactly the reversal of the corruption and nothing more. The minimal edit is defined by construction.

The metric is token-level Levenshtein distance on the Python tokenizer output, not raw character distance. This matters because a rename from `add` to `someotherfunctionname` is character-level huge but token-level tiny. Token-level Levenshtein captures the kind of structural change that actually matters for review.

Crucially, the author measures both the model's output against the ground truth and the model's output against the corrupted input. This gives you a clean signal on how much the model diverged from the minimal edit, independent of whether it got the bug right.

## What developers should actually do

You cannot fix this at the model level. You can work around it at the workflow level, and several of the mitigations are cheap.

First, prompt for restraint explicitly. The instruction "make the minimal change required to fix this bug. Do not rename, refactor, or add validation unless I ask." is not a magic spell, but it measurably reduces over-editing on [Claude Code](/blog/what-is-claude-code-complete-guide-2026) and Cursor in informal testing. Put it in your system prompt or your `CLAUDE.md`. Do not assume the model defaults to restraint.

Second, review the diff before you review the result. Pass@1 success tells you nothing about how much noise the model produced getting there. Look at the diff size. If the diff is larger than the bug, read it line by line. If the diff is larger than ten lines for a single-character bug, revert and re-prompt.

Third, keep bug-fix commits and refactor commits separate. If the model wants to clean up the function, let it, but in a separate commit that you can review as a refactor. Do not let refactors tunnel under bug fixes into the history. Future you, reading `git blame` in six months, will thank present you.

Fourth, turn down the reasoning dial. Counterintuitively, lower-reasoning-effort settings often produce cleaner diffs than high-reasoning-effort settings on small bugs. If your agent has a reasoning slider, use it. A maximum-reasoning agent is not always the agent you want on a two-character fix.

Fifth, consider tools that scope the agent's edit surface. The new generation of agent harnesses is experimenting with edit-range constraints, where the agent literally cannot modify lines outside a specified span. That is a more durable solution than prompting and one worth tracking as the primitives mature.

## The deeper point

Every [coding agent](/blog/what-is-an-ai-coding-agent-2026) we use today is an optimizer for passing tests. None of them are optimizers for minimal diffs. The benchmarks that the industry reports are pass rates, not edit distances. Until the scoreboards change, the model behavior will not change.

The nrehiew essay is useful because it argues for a second axis on the scoreboard. Correct and minimal, not correct or maximal. If that framing catches on in the next wave of benchmarks, the shape of the agents we build will follow. In the meantime, the restraint has to come from the prompt, the review, and the commit discipline.

If you are shipping with an AI coding agent in production, this is a problem worth understanding now. Not because it blocks the work, but because it quietly makes every code review, every merge conflict, and every history bisect more expensive than it needs to be.

Read [the full essay](https://nrehiew.github.io/blog/minimal_editing/). It is worth the twenty minutes.

## Frequently Asked Questions

### What is over-editing in AI coding agents?

A model is over-editing if its output is functionally correct but structurally diverges from the original code more than the minimal fix requires. The bug gets fixed, but a helper you did not request appears, a variable is renamed because the model thought the new name was clearer, and input validation is bolted onto a path that never needed it.

### Why cannot tests catch over-editing?

Tests verify correctness. They do not verify restraint. If the code is functionally correct, every green check still turns green and Pass@1 stays at 100 percent. Tests cannot tell you whether the model respected the shape of your code, whether a refactor snuck in under the cover of a bug fix, or whether variable names drifted. That verification has to happen in code review.

### Why do AI coding models over-edit?

Three causes are happening at once: training incentive, where RLHF rewards thorough, helpful-looking answers so the model learns that big diffs win; reasoning models are worse, because high-reasoning-effort settings make over-editing worse, not better; and context loss, where models regenerate the function from scratch and merge their approximation back, baking in drift.

### How can developers reduce over-editing?

Prompt for restraint explicitly with an instruction like "make the minimal change required to fix this bug. Do not rename, refactor, or add validation unless I ask." Review the diff before you review the result. Keep bug-fix commits and refactor commits separate. Turn down the reasoning dial, since lower-reasoning-effort settings often produce cleaner diffs on small bugs.

### Does higher reasoning effort produce better code edits?

No. Counterintuitively, lower-reasoning-effort settings often produce cleaner diffs than high-reasoning-effort settings on small bugs. High-reasoning-effort settings make the over-editing problem worse, because the model reasons its way into additional changes that feel defensible in chain-of-thought but that were never requested. A maximum-reasoning agent is not always the agent you want on a two-character fix.

## Further reading

- [Aider vs Claude Code: 2026 Update](/blog/aider-vs-claude-code-2026-update)
- [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026)
- [AI-Native Development Workflow](/blog/ai-native-development-workflow)


Qwen3.6-27B: A 27-Billion-Parameter Dense Model That Actually Codes
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## A 27B dense model is newsworthy again

The top of Hacker News this morning is Alibaba's new Qwen3.6-27B announcement, sitting at 691 points and more than 339 comments as I write this. The headline most people are reacting to is the positioning - "flagship-level coding in a 27B dense model." That phrasing is doing a lot of work, and it matters.

Dense means every one of those 27 billion parameters is activated for every forward pass. No mixture-of-experts routing, no sparse activation, no "we have 480 billion parameters but only 35 billion fire per token" footnote. What you see is what you run. In an ecosystem that has spent the last eighteen months chasing MoE scaling, a flagship-positioned dense model is a bet that the quality ceiling of dense architectures has not been fully mined yet, even at sizes that fit comfortably on a single high-end consumer GPU.

## Why this release lands differently

Qwen already ships [Qwen 3 Coder](/blog/qwen-3-coder) at 480 billion total parameters with 35 billion active. That model is an absolute unit. It runs benchmark-level code generation. It also requires either a serious multi-GPU host or an API endpoint. Most developers end up renting it.

Qwen3.6-27B is the other half of the strategy. One model you rent. One model you own. A 27B dense checkpoint in 4-bit quantization lands at roughly 14 GB of weights, which fits on a single RTX 4090, a single H100, or any of the new 32GB-plus developer-class machines that shipped over the past year. On my own DGX Spark box I already run Qwen3.5 at 27B alongside a 35B and a 122B. Slotting Qwen3.6-27B in is a one-line change. The point is that "flagship-level coding" stops being a cloud-only experience.

## The dense versus MoE tradeoff, in practical terms

MoE models win on throughput per active parameter. They are cheap to serve at scale because only a fraction of the network fires per token. They are harder to run locally because you still need to hold every expert in memory, even the ones you rarely touch. A 480B MoE with 35B active still needs 480B worth of weights resident somewhere.

Dense models lose on throughput per active parameter. They are expensive to serve at scale because every parameter fires every time. They are dramatically easier to run locally because the memory footprint equals the total parameter count. No expert sharding, no routing overhead, no imbalanced GPU utilization. For a solo developer who wants a fast, capable coding model on one machine, dense at 20B to 30B is the sweet spot. Qwen3.6-27B is exactly in the middle of that sweet spot.

There is also a second-order benefit that gets underreported. Dense models are easier to fine-tune. The gradient flows cleanly through every parameter. MoE fine-tuning introduces routing instabilities, expert-specialization collapse, and a stack of tricks that most practitioners would rather skip. If you want to take a base model and domain-adapt it to your own codebase or your own skill library, a 27B dense checkpoint is a much friendlier starting point than a 480B MoE.

## What to actually look for in the benchmarks

I am going to be honest. Model announcements are marketing. Until someone independent runs HumanEval-plus, SWE-bench Verified, LiveCodeBench, and a handful of real-world agentic tasks, the "flagship-level" claim is a vibes claim. Here is the short list of numbers that would make this release a genuine shift rather than an iteration.

First, SWE-bench Verified. If Qwen3.6-27B lands meaningfully above 50 percent solved on SWE-bench Verified in an unaided single-shot setting, that is genuinely impressive for a dense model of this size. For reference, that is territory previously held by 70B-plus dense models and frontier closed models.

Second, long-context code retrieval. Coding agents live or die on their ability to pull the relevant thirty lines out of a 200K-token repository context. Needle-in-haystack at 128K is table stakes in 2026. Needle-in-code at 128K is still a place where many open models fall over.

Third, [tool use](/blog/tool-use-claude-api-production-patterns) reliability. A coding model that hallucinates function signatures or invents filesystem paths is useless inside an agent loop. Tool-use faithfulness metrics are boring to read but they are the difference between "this model is a demo" and "this model ships work."

If Qwen3.6-27B posts credible numbers in those three categories, the right move is to wire it into your local agent stack this weekend.

## How to try it today

The fastest path is Ollama. Alibaba historically ships Qwen checkpoints to Hugging Face within hours of the blog post, and the Ollama team usually has a model manifest up within a day or two. If you are on a single consumer GPU, pull the 4-bit quantization first and only move to 8-bit if you have memory headroom. Plug it into any [OpenAI](/blog/openai-vs-anthropic-2026)-compatible frontend - Cline, Continue.dev, Roo Code, or the bare Ollama CLI all work.

If you run a serious local rig, consider vLLM over llama.cpp for throughput. Qwen's recent checkpoints have first-class vLLM support and the server mode pairs cleanly with [coding agents](/blog/what-is-an-ai-coding-agent-2026) that expect streaming token responses.

One thing worth doing is evaluating it against your own codebase, not against public benchmarks. Point it at twenty issues from your real repo. Ask it to implement each one. Grade the diffs yourself. Public benchmarks are good for ranking models in the abstract. Private benchmarks tell you whether a model actually ships your work.

## The deeper story

The Qwen team has been running a strategy that most Western labs have not figured out how to copy. They release fast. They release across size tiers. They release with permissive licenses. They release dense, MoE, coder-specialized, and multimodal in parallel. They make every model immediately runnable on consumer hardware. And they do it on a six-to-twelve-week cadence.

A 27B dense coder is not the biggest model in the Qwen family and it will not be the most quoted. But it is the one that puts frontier coding quality onto the hard drive of every serious developer who owns a single good GPU. That is a different kind of news than "we added 10 points to HumanEval."

If the benchmarks hold up when the independent numbers come in, this is the model a lot of local-first developers have been waiting for. If they do not hold up, the direction of the release is still the right one. Dense, downloadable, runnable, and sized for the hardware we actually own.

I will be benchmarking it on my own stack this week. If the numbers are interesting, I will post a follow-up with real diffs, real pass rates, and a head-to-head against Qwen3.5-27B and the 480B Coder. Until then, the release itself is worth the download.

## Further reading

- [Qwen 3 Coder: Alibaba's Coding-Optimized LLM](/blog/qwen-3-coder) - the 480B MoE sibling
- [Qwen 3: The Complete Guide](/blog/qwen-3-guide) - background on the Qwen family
- [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026) - where Qwen fits in the landscape


7 AI Agent Orchestration Patterns Every Developer Should Know
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## The vocabulary developers are missing

One of the quieter frustrations of 2026 AI development is that everyone is building [multi-agent systems](/blog/multi-agent-systems) and no two people are using the same words for the shapes. Someone says "I spawned a swarm." Another says "I ran a supervisor." A third says "I pipelined it." The shapes are real. The vocabulary is not yet shared.

This post catalogs the seven patterns that keep showing up when developers wire [AI agents](/blog/ai-agents-explained) together in production. It is not an exhaustive taxonomy. It is the minimum shared vocabulary that makes architecture conversations productive. Pick the pattern that matches your problem, understand the tradeoffs, combine them when needed.

## 1. Single Agent

The baseline. One model, one system prompt, one task. No orchestration.

**When it works:** the task is self-contained, the context fits in a single window, no specialized tools or hand-offs are needed. Write a function, summarize a doc, answer a question.

**When it breaks:** the task requires multiple areas of expertise, the output needs verification from a different perspective, or the work exceeds a single context window.

**Implementation:**
```bash
claude -p "Refactor this function to use async/await"
```

That is the entire pattern. The moment you reach for a second agent, you have left this pattern.

**The mistake here:** jumping to orchestration too early. Most tasks do not need a supervisor. Most tasks do not need a swarm. Start with one agent, prove you need more, then reach for a heavier pattern.

## 2. Supervisor

One coordinator agent receives the task, decomposes it, routes subtasks to specialists, and synthesizes results.

```
User → Supervisor
          │
   ┌──────┼──────┐
Agent A  Agent B  Agent C
(research) (code) (review)
          │
       Supervisor → Response
```

**When to use:** two to five distinct subtasks requiring different expertise, you want a single point of control and quality gating, subtasks can run in parallel but results need synthesis.

**Implementation in [Claude Code](/blog/what-is-claude-code-complete-guide-2026):** the supervisor uses the Task tool to spawn subagents. Each subagent gets a focused system prompt and a scoped set of tools. The supervisor collects results and decides what to do next.

**Real example:** the DevDigest `/devdigest:research` skill spawns parallel research agents, one per source, then a supervisor synthesizes findings into a structured brief.

**Tradeoffs:** clean separation of concerns and easy to debug, but the supervisor is a bottleneck. If it misroutes, everything fails. Quality of the final output is roughly proportional to the quality of the supervisor's task decomposition.

## 3. Pipeline

Sequential processing where each stage's output becomes the next stage's input. Unix pipes for agents.

```
Input → Stage 1 → Stage 2 → Stage 3 → Output
       (scrape)  (analyze) (format)
```

**When to use:** work that is naturally sequential (research, then write, then review), each stage needing different tools or models, a desire for checkpoints between stages.

**Implementation:** each stage is a separate `claude -p` call. Intermediate results written to files on disk. The next stage reads from disk, processes, writes its output. A shell script or cron orchestrates.

**Real example:** a video production pipeline. Firecrawl scrapes sources to `/tmp/research/`. A research agent reads those files, produces `research/summary.md`. A script agent reads the summary, produces `script.md`. A production agent reads the script, produces a YouTube description and thumbnail brief.

**Tradeoffs:** simple, debuggable, resumable from any stage, but no parallelism. If your stages are actually independent, pipeline is slower than it needs to be.

## 4. Swarm

Fan out N independent tasks to parallel workers. All run simultaneously. Results collected and merged.

```
       Coordinator
      /     │     \
Worker    Worker   Worker
(task 1)  (task 2) (task 3)
      \     │     /
        Collector
```

**When to use:** you have N independent, similar tasks. Audit N repos. Research N topics. Process N files. Each task is self-contained and does not depend on others. Speed matters.

**Implementation in Claude Code:** use the Task tool to spawn multiple agents in a single message. Each gets the same instructions with different input data. Results are collected when all complete.

**Real example:** an email triage skill that spawns ten parallel agents, one per Gmail label, to analyze the inbox concurrently. Ten minutes of serial work becomes one minute of parallel work.

**Tradeoffs:** linear speedup with worker count and trivially parallelizable, but no inter-worker communication. If tasks actually depend on each other, swarm produces inconsistent output.

The practical rule: if you cannot write down each worker's instructions before spawning any of them, swarm is not the pattern.

## 5. Debate

Two or more agents take opposing positions on a question. A judge agent evaluates and picks a winner, or synthesizes a balanced answer.

```
Question → Agent A (pro) → Judge → Answer
         → Agent B (con)
```

**When to use:** decision-making with real tradeoffs. Technology choice, architecture decision, scope cut. You want to surface arguments you might not have considered.

**Implementation:** spawn two agents with opposing system prompts ("argue for X", "argue against X"). Feed both responses to a judge agent. The judge synthesizes or picks a winner with reasoning.

**Real example:** evaluating "should we use Convex or Neon for this feature?" One agent argues real-time. The other argues relational. The judge decides based on the specific requirements the feature actually has.

**Tradeoffs:** surfaces blind spots and produces higher-quality decisions, but [costs](/blog/ai-coding-tools-pricing-comparison) three times the tokens of a single-agent answer. Overkill for straightforward tasks. Worth the cost for decisions you will live with for a year.

## 6. Hierarchical

Multi-level delegation tree. A director sets strategy, managers decompose into tasks, workers execute.

```
       Director
      /        \
 Manager A    Manager B
  /    \       /    \
Wkr   Wkr    Wkr   Wkr
```

**When to use:** large, complex projects that naturally decompose into teams with different expertise. Build an entire app. Audit a complete codebase. Produce an end-to-end deliverable.

**Implementation:** a director agent plans the overall approach and creates manager-level tasks. Each manager decomposes its area and spawns workers. Workers execute and report up. Managers synthesize. Director receives the final rollup.

**Real example:** a full-stack app build delegated to auth, database, UI, and deployment managers. Each manager owns its sub-tree. The director only sees final rollups from each area.

**Tradeoffs:** scales to large projects with clean responsibility boundaries, but communication overhead between levels grows quickly. Debugging is painful when a bug hides under three layers of delegation. Expensive. Reserve for tasks that genuinely need it.

## 7. Harness

Not a one-shot orchestration pattern but a persistent environment that agents live in. The harness compounds across sessions through memory, hooks, skills, and cron.

```
Inputs (email, git, web, meetings)
          │
   ┌──────▼──────┐
   │   HARNESS    │
   │  Memory      │ ← persists across sessions
   │  Hooks       │ ← event-driven automation
   │  Skills      │ ← packaged capabilities
   │  Subagents   │ ← parallel workers
   │  Cron        │ ← scheduled tasks
   └──────┬──────┘
          │
  Outputs (code, emails, docs, deploys)
          │
   ┌──────▼──────┐
   │ Learn loop   │ ← harness improves itself
   └─────────────┘
```

The six harness primitives you actually compose:

1. `CLAUDE.md` - identity and rules, loaded every session
2. Memory - persistent markdown the model reads and writes
3. Hooks - event-driven scripts (PreToolUse, PostToolUse, Stop)
4. Skills - packaged capabilities with progressive disclosure
5. Subagents - parallel workers spawned via the Task tool
6. Headless mode - `claude -p` for cron, CI, and scripting

**When to use:** you want an agent system that gets better over time. You have recurring workflows (daily email triage, weekly reporting). You want to encode institutional knowledge that persists across sessions.

**Tradeoffs:** compounds over time (every session builds on the last), but requires setup investment and file organization discipline. The first week feels like overhead. The third month feels like a superpower.

## Choosing a pattern

The decision tree in one paragraph: is the task a single scoped question? Single Agent. Can it split into independent chunks? Swarm. Is it a sequence where each step feeds the next? Pipeline. Does it need multiple areas of expertise with synthesis? Supervisor. Is it a decision with real tradeoffs? Debate. Is it a large project with teams and sub-teams? Hierarchical. Do you want an always-on system that improves? Harness.

## Patterns combine

In practice, the interesting work happens at the seams.

- **Harness + Swarm.** The harness cron triggers a swarm of research agents every morning.
- **Supervisor + Pipeline.** A supervisor decomposes work, each subtask is a mini-pipeline.
- **Hierarchical + Debate.** Manager agents debate approach before directing workers.
- **Pipeline + Swarm.** Each pipeline stage fans out to parallel workers.

Most production systems are actually a Harness with one or two of the other patterns layered inside. The Harness provides persistence and scheduling. The inner pattern handles the task shape.

## The tool map

| Tool | Best fit | Notes |
|------|---------|-------|
| Claude Code (Task tool) | Supervisor, Swarm, Hierarchical | Native subagent support |
| Claude Code (headless) | Pipeline, Harness, Cron | `claude -p` for scripting |
| Claude Managed Agents | Long-running supervised agents | Cloud-hosted |
| LangGraph | Complex state machines | Good for Debate, Hierarchical |
| CrewAI | Role-based teams | Opinionated Supervisor |
| AutoGen | Multi-agent conversations | Good for Debate |

Most developers I know start with Claude Code because it supports most patterns natively, then reach for LangGraph or AutoGen when they need a state machine complex enough that markdown files and shell scripts are no longer enough.

## The meta-point

Pattern literacy is the shortcut that lets you build the right system the first time. If you know your problem is a Swarm, you will not accidentally build a Supervisor and wonder why it is slow. If you know you want a Harness, you will invest in the primitives early rather than rebuilding them for every new script.

The seven patterns are not academic. They are what show up after a year of shipping agents. The faster you learn to name the shape you are building, the faster you stop fighting the tools.

## Frequently Asked Questions

### What is AI agent orchestration?

Agent orchestration is the practice of coordinating multiple AI agents to complete a task. Instead of one model handling everything, you split work across specialists - a researcher, a coder, a reviewer - and wire them together. The orchestration layer handles task decomposition, routing, parallel execution, and result synthesis.

### Which orchestration pattern should I start with?

Start with Single Agent. Most tasks do not need orchestration. If you find yourself thinking "I wish this agent could also do X at the same time," then reach for Supervisor (for 2-5 subtasks) or Swarm (for N independent parallel tasks). Add complexity only when a simpler pattern fails.

### What is the difference between a Supervisor and a Pipeline?

A Supervisor decomposes work, routes it to specialists in parallel, and synthesizes results. A Pipeline processes sequentially - stage 1 output becomes stage 2 input. Use Supervisor when subtasks are independent and can run simultaneously. Use Pipeline when each stage genuinely depends on the previous one.

### When should I use a Swarm pattern?

Use Swarm when you have N similar, independent tasks - audit 10 repos, research 8 topics, process 50 files. The key test: can you write each worker's instructions before spawning any of them? If workers need to coordinate or depend on each other's output, Swarm is the wrong pattern.

### What is a Harness in AI agent orchestration?

A Harness is not a one-shot pattern but a persistent environment that agents live in across sessions. It includes memory (persistent markdown), hooks (event-driven automation), skills (packaged capabilities), subagents, and scheduled tasks. The Harness compounds over time as every session builds on the last.

### How do I implement these patterns in Claude Code?

Claude Code supports most patterns natively. Single Agent is just `claude -p "task"`. Supervisor and Swarm use the Task tool to spawn parallel subagents. Pipeline chains `claude -p` calls with file-based intermediate results. Harness uses CLAUDE.md, hooks, skills, and headless mode for cron. See [Building Multi-Agent Workflows with Claude Code](/blog/building-multi-agent-workflows-claude-code) for implementation details.

### How do I choose between Debate and single-agent decision making?

Use Debate when you face a decision with real tradeoffs - technology choice, architecture decision, scope cut - and want to surface arguments you might not have considered. Debate costs three times the tokens (two advocates plus a judge) but produces higher-quality decisions. For straightforward questions, stick with a single agent.

### Can I combine multiple orchestration patterns?

Yes, most production systems combine patterns. A Harness triggers a Swarm of research agents every morning. A Supervisor decomposes work where each subtask is a mini-Pipeline. Manager agents in a Hierarchical system Debate approach before directing workers. The Harness typically provides persistence and scheduling while an inner pattern handles the task shape.

## Further reading

- [Zed's Parallel Agents: The Editor Catches Up](/blog/zed-parallel-agents-first-editor-making-it-native) - Swarm at the editor layer
- [Building Multi-Agent Workflows with Claude Code](/blog/building-multi-agent-workflows-claude-code)
- [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026)


Zed Just Made Parallel AI Agents a Native Editor Primitive
Developers Digest — Wed, 22 Apr 2026 00:00:00 GMT
## The editor finally caught up to how we actually work

If you have been running more than one [AI coding agent](/blog/what-is-an-ai-coding-agent-2026) at a time this year, you have been doing it manually. You opened a second Claude Code tab. You spun up a second Cursor window. You shelled out to Aider in a second terminal. You kept a mental map of which agent was in which worktree on which branch. You switched contexts by squinting at a window title bar.

[Zed just shipped a feature](https://zed.dev/blog/parallel-agents) that treats that workflow as the default instead of the exception. Parallel Agents is not a plugin or a marketplace extension. It is a native editor panel. The HN thread is sitting at 168 points and 104 comments as I write this, and it is the first major code editor to make multi-agent orchestration a first-class primitive rather than something you cobble together.

This is a bigger deal than the announcement makes it look.

## What Zed actually shipped

The headline feature is the Threads Sidebar. Threads dock on the left by default, next to the Agent Panel. Project and Git panels move to the right. Each thread is an independent agent session with its own scoped access. The sidebar lets you start, stop, archive, and monitor threads from a single view, grouped by project.

A few specifics worth pulling out because they are where the design thought happened.

**Per-thread agent selection.** Zed lets you choose which agent runs in which thread. You can keep Claude for the hard refactor, [Codex](/blog/openai-codex-guide) for the bugfix, GPT for the doc generation, and a local Ollama model for the playground thread. All in the same editor window, all at the same time.

**Per-thread worktree isolation.** You can pin a thread to a specific folder or repository. If your repo is set up with worktrees, you can keep three threads hammering three different worktrees without any of them seeing the others' uncommitted state. This was the single most painful part of parallel agent work before, because coordination failure at the filesystem level produces silent bugs that are hard to trace.

**Cross-project threads.** The inverse is also true. If you want one thread reading and writing across multiple repos, the sidebar supports it. That is a meaningful difference from the implicit single-root assumption in most editors.

**Everything runs at 120 fps, open source, and works with any agent backend [Zed](/blog/zed-agentic-ide) supports.** Agent choice is not gated by a paid plan.

## Why this is the right architecture

Multi-agent workflows are not new. The craft has been shipping in the form of `tmux` splits, multiple terminal tabs, and hand-rolled worktree scripts for at least eighteen months. I run five to eight parallel [Claude Code](/blog/what-is-claude-code-complete-guide-2026) sessions on a productive day. Every serious AI-native engineer I know has a similar setup.

What has been missing is an editor that assumes the workflow exists. Cursor's chat UI is single-threaded by design. VS Code with Copilot Chat is single-threaded by default. Aider is CLI-first and the multi-session workflow is a shell problem, not an editor problem. Claude Code runs in the terminal and you stack sessions by opening more terminal windows. All of these work. None of them make parallel the default.

Zed saying "threads are how you use the editor" is an architectural statement. The implication is that single-agent thinking is the weird case, not the common case. Everything about the new default layout, the thread grouping by project, the per-thread settings, the worktree isolation, the agent switcher, reads as "we assume you have five of these going."

That is the right read of 2026 reality. The models have gotten fast enough that one agent is rarely the bottleneck. The bottleneck is humans, and specifically the cost of holding multiple lines of work in your head at once. A good editor makes the cost of that holding cheaper.

## What this validates about the rest of the stack

The parallel-first design also validates a set of adjacent practices that have been emerging across the AI dev tooling space.

**Worktrees are the right unit of isolation.** Claude Code's worktree workflow, where each task gets its own ephemeral worktree on a branch, has been the best available answer to "how do I run three agents on the same repo without them stepping on each other." Zed's per-thread worktree pin takes the same idea and makes it navigable from the sidebar. The implicit endorsement is significant.

**Agent-mixing is real.** For a while, the industry framing was that you picked your agent and stayed loyal. Cursor users were Cursor users. Claude Code users were Claude Code users. In practice, most productive engineers I know rotate through three or four agents depending on the task. Zed has built the editor that acknowledges this. Claude for long-context refactors. GPT for small, fast edits. Local models for anything you do not want hitting an API. Pick the right tool per job, per thread.

**Monitoring is part of the loop.** One of the quieter parts of the Zed post is that the sidebar lets you monitor threads as they run. Not just review their final output but watch them work. That is a direct response to the failure mode where you set five agents going and come back to four unfinished runs and one that rewrote your auth system because a retry loop got stuck. Visibility is a safety feature when parallelism goes up.

## What it still does not solve

Parallel agents are an editor-level win. They are not a reasoning-level win.

The hard problem of parallel AI work is coordination, not execution. Three agents running on three worktrees is great until two of them want to refactor the same interface in incompatible ways. Then you have three diffs you cannot cleanly merge and the gain you got from parallelism evaporates into conflict resolution overhead. The editor does not solve this. Nothing in the industry solves this yet. The practical workaround is aggressive scoping. Each thread gets a task small enough to finish in one pass and narrow enough that the blast radius is contained. That is a human discipline, not a tool feature.

The other thing parallel agents do not solve is the restraint problem. If you have read [our piece on over-editing](/blog/over-editing-when-ai-rewrites-what-isnt-broken) from earlier today, you know that one agent can produce a 50-line diff for a one-character bug. Five agents can produce 250 lines. Parallelism is a throughput multiplier, including for the bad habits. The Zed sidebar gives you the visibility to catch this but it does not prevent it.

## The strategic read

Zed is positioning itself as the editor that takes agentic engineering seriously. Nathan Sobo, Zed's co-founder, coined the phrase "agentic engineering" in a 2025 post that framed the craft as "combining human craftsmanship with AI tools to build better software." That framing is now concrete in the product. The parallel agents feature is Zed saying that the editor is the place where this craft happens, and that the competition is not Cursor or VS Code, it is the set of hand-rolled workflows that developers have been cobbling together from `tmux`, worktrees, and multiple terminal tabs.

That is a smart position to take. The vendors that are going to win the next eighteen months are the ones that make multi-agent workflows feel native rather than bolted on. Cursor's chat-first UX has not made the leap yet. VS Code is shackled by backwards compatibility with the single-window assumption that Copilot was built on. Claude Code and its CLI peers are excellent but they are terminal tools, not editor-level environments.

If you have been running parallel agents by hand for months and building mental scaffolding to keep them coordinated, Zed just made that scaffolding disappear into the editor. That alone is enough to make the switch worth trying.

## How to try it

Download Zed, or update to the latest version if you already have it. Open the Threads Sidebar from the icon in the bottom-left, or use `option-cmd-j` on macOS or `ctrl-option-j` on Linux and Windows. The new default layout is opt-in for existing users, so you will need to flip the layout yourself.

Start with three threads on three scoped tasks. A small bugfix, a doc update, and a test coverage pass. Use a different agent per thread. Watch them work from the sidebar. If you come away thinking it felt smoother than whatever you were doing before, that is the signal. If you come away thinking it felt like more windows to manage, you probably need to scope the tasks smaller.

The editor is catching up to how we actually work. Adjust accordingly.

## Further reading

- [Building Multi-Agent Workflows with Claude Code](/blog/building-multi-agent-workflows-claude-code)
- [Best AI Coding Tools in 2026](/blog/best-ai-coding-tools-2026)
- [Over-Editing: Why Your AI Agent Rewrites What Isn't Broken](/blog/over-editing-when-ai-rewrites-what-isnt-broken)


Chronicle Research Preview Setup Guide
Developers Digest — Tue, 21 Apr 2026 00:00:00 GMT

# Chronicle Setup Guide

Chronicle is in an opt-in research preview and is only available for ChatGPT Pro subscribers on macOS. It is not yet available in the EU, UK, or Switzerland.

Chronicle augments Codex memories with context from your screen so prompts can pick up work-in-progress context from recent activity.

Before enabling it, review the privacy and security section and understand the risks.

## How Chronicle helps

Chronicle can reduce the amount of context you need to restate when working with Codex.

In practice it helps with:

- Using what is visible on screen so Codex can follow what you are currently looking at
- Filling missing context when you jump between tasks
- Remembering tools and workflows that you repeatedly use

In the right cases, Codex uses Chronicle context to identify the best source, such as a file, Slack thread, Google Doc, dashboard, or pull request.

## Enable Chronicle

1. Open **Settings** in the Codex app.
2. Go to **Personalization** and enable **Memories**.
3. Turn on **Chronicle** below Memories.
4. Review the consent dialog and choose **Continue**.
5. Grant macOS **Screen Recording** and **Accessibility** permissions when prompted.
6. When setup completes, choose **Try it out** or start a new thread.

If macOS reports that a permission is denied, open **System Settings > Privacy & Security** and enable Codex under **Screen Recording** and **Accessibility**.

If a permission is restricted by macOS or your organization, Chronicle will start once the restriction is removed and permissions are granted.

## Pause or disable Chronicle

You can pause and resume Chronicle from the Codex menu bar icon at any time.

- Use **Pause Chronicle** before meetings or when viewing sensitive content.
- Use **Resume Chronicle** when you want context to be captured again.

To disable it permanently:

1. Open **Settings > Personalization > Memories**.
2. Turn off **Chronicle**.

You can also control whether memories are used on a per-thread basis from the memories settings docs.

## Rate limits

Chronicle runs background agents that summarize captured screen images into memories, and these agents can consume rate limits quickly.

## Privacy and security

Chronicle uses screen captures and does not have access to microphone or system audio.

### Where it stores data

- Temporary screen captures appear under `$TMPDIR/chronicle/screen_recording/` while Chronicle is running. Frames older than 6 hours are deleted while running.
- Generated memories are saved in markdown files under `$CODEX_HOME/memories_extensions/chronicle/` (usually `~/.codex/memories_extensions/chronicle`).

Both locations can contain sensitive information. Do not share them with others.

You can ask Codex to search these memories. If you want Codex to forget something, delete or edit the respective markdown file.

### What data gets shared with OpenAI

Chronicle captures are processed locally first, then summarized by Codex using selected screenshot frames, OCR text, timing, and local file paths.

Temporary screen captures are processed on OpenAI servers only for memory generation. OpenAI does not store screenshots after processing unless required by law, and does not use them for training.

The generated memories stay local in `$CODEX_HOME/memories_extensions/chronicle/`.

Relevant memory contents can be included as context in future sessions.

## Prompt injection risk

Chronicle increases prompt injection risk from screen content. If you open a site with malicious instructions, Codex can be tricked into following them. Be cautious when running Chronicle in high-risk browsing environments.

## Troubleshooting

### I do not see the Chronicle setting

1. Confirm you are on a Codex app build that includes Chronicle.
2. Confirm **Memories** is enabled in **Settings > Personalization**.
3. Confirm Chronicle is available for your region and subscription tier.

### Setup does not complete

1. Confirm Codex has **Screen Recording** and **Accessibility** permissions.
2. Quit and reopen the Codex app.
3. Open **Settings > Personalization** and check Chronicle status.

### Which model is used for Chronicle memories

Chronicle uses the same model as your other memories.

If you did not set a specific model, it uses the default Codex model. To pin one, set `consolidation_model` in configuration.

```toml
[memories]
consolidation_model = "gpt-5.4-mini"
```


The $400 Overnight Bill: Why Managed Agents Need FinOps Now
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
## The $437 Morning

I woke up to a $437 bill from an agent I asked to write a TypeScript refactor.

For cost context, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) alongside [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); together they separate sticker price from the operational habits that make agent work expensive.

The task was not small but it was not $437 big. Port a mid-sized service from a bespoke event emitter to a typed pub/sub primitive, update the tests, open a PR. I spun it up around 11pm, watched the first few steps, saw it start editing the right files, and went to bed. When I opened my laptop at 7am there was no PR. There was a still-running session, a loop counter past 200, and a billing dashboard that made me close the tab and open it again to make sure I was reading it right.

What actually happened was mundane. The agent hit a failing test, tried to fix it, broke a neighboring test, tried to fix that, went back to the first one, and kept oscillating. Each pass retried a web search. Each pass re-read the file tree. There was no per-session cap. There was no cross-provider ceiling. There was no kill switch attached to dollars. There was only the assumption, inherited from a decade of SaaS, that the bill at the end of the month would be roughly the bill I expected at the start of it. Managed agents broke that assumption and nobody has rebuilt it yet.

## Why It Is Getting Worse

The managed-agent category just crystallized. Anthropic launched Claude Managed Agents on April 9, 2026 with a pricing surface that combines model tokens, a session-hour charge of $0.08/hour, and tool surcharges on top (web search is billed at $10 per 1,000 calls). Six days later, OpenAI shipped its [Agents SDK](/blog/openai-agents-sdk-typescript) update with a different shape: standard API tokens plus $0.03/GB for hosted sandbox sessions, with sandbox providers ranging across Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, and Vercel. That is two frontier providers, two pricing models, already incompatible before you leave the first tier.

Past that tier it fractures more. Devin prices in ACUs, where one ACU is roughly 15 agent-minutes and plans scale from $20 pay-as-you-go to $500 for 250 ACUs. Cursor Background Agents ride on a Pro subscription with metered Max-mode overflow, and field reports are landing around $4.63 per "easy" PR. [GitHub Copilot](/blog/github-copilot-coding-agent-cli-2026) charges per-seat with 300 premium requests bundled and $0.04 for every overflow request. Replit has effort-based credits with Economy, Power, and Turbo tiers. Jules is free up to 15 tasks a day, then tiered. Factory is token-based with no per-seat floor.

Five [pricing](/blog/ai-coding-tools-pricing-2026) models (tokens, session-hour, per-task/ACU, per-seat with overflow, outcome-based) layered with infinite hybrids. No unified attribution. Every provider shows you their own dashboard, their own units, their own refresh cadence. When an overnight run goes sideways, piecing together what actually happened requires opening five browser tabs, correlating timestamps by hand, and trusting that each dashboard updated before you looked at it. The category grew up faster than its observability did, and FinOps is the thing that is missing.

## The Three Failure Modes

In my own logs and in enough war stories from other teams to call it a pattern, three specific failure modes account for almost every overnight blowup.

**1. Pathological loops.** The agent retries the same broken test two hundred times. This is what happened to me. It usually starts with a test that fails for a reason the agent cannot see (an environment variable, a flaky external call, a test depending on order), and the agent interprets the red bar as a code problem. It edits, reruns, edits, reruns. On Claude Managed Agents at $0.08/session-hour plus Opus 4.6 tokens at $5 input and $25 output per million, eight hours of this can clear $200 on tokens alone before you count the session fee. Prevention: every agent run gets a max-iterations cap in the harness, every test failure that recurs more than three times triggers an escalation to a human, and every session gets a hard dollar ceiling that kills the process rather than "warns" the user.

**2. Tool call explosion.** The agent decides it needs context and calls web search in a hot loop. Claude Managed Agents bills web search at $10 per 1,000 queries. It takes one broken retry pattern to rack up 3,000 searches across a single task, which is $30 in tool calls on top of whatever the model tokens cost. I have seen a [Cursor](/blog/what-is-cursor-ai-code-editor-2026) Background Agent run up 400 MCP calls in a session that should have needed six. Prevention: set per-tool quotas at the harness level (max 50 web searches per session, max 100 file reads, max 10 shell executions), log every tool call with its cost, and treat tool-call count as a first-class alert metric.

**3. Context swapping.** The agent keeps re-reading the same file tree. This one is quiet. Each pass through a task, the agent reloads the project structure, rereads five or ten files it has already seen, and pushes them into a fresh context window. On a 1M-context model like GPT-5.4, this is cheap in wall time but expensive in tokens because you are sending 300K input tokens per iteration and compaction does not always kick in the way you want. Ten iterations at 300K input tokens each is 3M tokens per session, and on GPT-5.3-Codex at $1.75 input per million that is $5 per run, per agent, before you add output. Run five agents in parallel overnight and you spent $25 on file rereads. Prevention: force the harness to use compaction aggressively, cache file contents with hash keys across iterations, and instrument input-token growth per step so that a reread spike is visible before the bill is.

## What Is Missing In The Market

No one has cross-provider cost attribution. Say that again with the weight it deserves. You can go to Anthropic's dashboard and see tokens and session hours. You can go to OpenAI's dashboard and see tokens and sandbox storage. You can go to Devin and see ACUs. You can go to Cursor and see Max-mode overflow. You cannot go to any dashboard today and see a single task called "refactor the event emitter" with the total cost across the two frontier providers, the one sandbox vendor, and the one web-search tool it touched. That span does not exist.

What you need is straightforward to describe and has been refused by the market for eighteen months. You need unified spans tagged per-agent, per-user, per-task, with model tokens, session time, tool calls, and dollar cost attached to each span. You need parent-child span relationships so that a task like "run the test suite" groups its twenty tool calls under a single parent, and a larger task like "ship this PR" groups the test-suite span under itself. You need the ability to filter by provider, by model, by user, and by task and get the exact dollar number out.

This is the OpenTelemetry trace model. OTel already has the vocabulary: traces, spans, resource attributes, semantic conventions. The GenAI semantic conventions already define `gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.input_tokens`, and `gen_ai.usage.output_tokens`. What is missing is adoption by managed-agent providers, a coherent cost enrichment layer sitting on top of those spans, and a receiver that holds the data close enough to you that you can ask questions across providers without waiting for each vendor's BI team to ship a feature.

## The DD Traces Angle

DD Traces was built for exactly this gap. Today it does local OTel trace collection. The minimal OTLP receiver shipped last week and already ingests spans from Claude Code, Cursor, Codex, Augment, Gemini, and Kimi sessions running on your machine. You point an OTLP exporter at `localhost:4318`, you run your agents, and you get a unified view of what ran where.

Cost attribution is the next step and I am not going to pretend it is done. The piece that exists is the trace plumbing and the cross-tool schema. The piece that is TODO is the enrichment layer that reads a span's provider and model, looks up the current pricing, multiplies the tokens and tool calls, and attaches a dollar figure as a span attribute. That layer is in the roadmap, not in `main`, and the honest framing is: we have the pipes, we have the schema, we do not yet have the pricing table plugged in or the budget-ceiling kill switch wired up.

Where we are thinking next: a pricing table for Claude Managed Agents, OpenAI Agents SDK, Devin, Cursor, and Copilot that updates weekly. A `dollars_spent` attribute enriched onto every span at ingest time. A dashboard view that filters by provider, model, user, and task. A budget alert that fires when a single trace crosses a ceiling, with a follow-on kill hook that can signal the harness to stop. That is what FinOps for managed agents looks like and it is what DD Traces is building toward.

If you want to watch that happen, the project is at [traces.developersdigest.tech](https://traces.developersdigest.tech) and the receiver is MIT licensed. Opinions on semantic conventions, pricing sources, and kill-hook design are welcome and frankly necessary.

## What To Do Tonight

You do not need DD Traces to protect yourself this week. Three concrete things, in order.

**1. Set hard dollar caps in each provider's UI.** Anthropic, OpenAI, Cursor, Devin, Copilot, and Replit all have usage limits under billing settings. Set them now, before the next overnight run. A cap that lives in the provider dashboard will not save you from bad code but it will save you from the worst version of "forgot to set a cap." Before you set the cap, run a quick estimate through our [AI cost calculator](/pricing) so the number you pick is grounded in actual token math rather than a guess. Set it per-workspace, set it per-key, set it aggressive (a 2x your expected monthly spend is fine, 10x is not).

**2. Run agents with OTel tracing turned on.** Every major agent framework now supports OTLP export: Claude Agent SDK, OpenAI Agents SDK, LangGraph, Mastra, Vercel AI SDK. Set `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` and send spans to any collector (DD Traces, Langfuse local, a plain file sink). Even without cost enrichment, having the traces on disk means you can reconstruct what happened when the bill arrives.

**3. Write a $10 sentinel loop.** The top action, the one that matters most if you do nothing else tonight: a shell script or cron job that polls each provider's usage API every 5 minutes, sums the spend since session start, and kills the agent process if it crosses a threshold you set. Ten dollars is a good first number because it is high enough to let real work finish and low enough that a runaway loop gets caught in the first hour. It is ugly and it works and it has saved me from another $437 morning more than once.

---

The managed-agent category is two weeks old in its current shape and the FinOps layer under it is weeks behind. Cost attribution across Claude, OpenAI, Devin, and Cursor is the next thing that has to exist for any serious team to run agents overnight without a finance conversation in the morning. DD Traces is one attempt at it. If you are running agents and want the trace layer today, grab it at [traces.developersdigest.tech](https://traces.developersdigest.tech). If you are picking which managed agent to run in the first place, the comparison lives at [agenthub.developersdigest.tech](https://agenthub.developersdigest.tech).

The $437 bill was a cheap lesson. The next one will not be.

## Frequently Asked Questions

### Why do AI agents run up unexpected bills overnight?

AI agents operate in loops - reason, act, observe, repeat. When an agent encounters an error it cannot resolve (like a flaky test or missing environment variable), it may retry the same failing step hundreds of times. Each retry consumes tokens, triggers tool calls, and accumulates session time. Without hard caps, this loop runs until you notice it or until a provider limit kicks in. The problem is compounded by multiple cost dimensions: model tokens, session hours, tool calls, and sandbox compute all bill separately.

### How do I prevent runaway AI agent costs?

Three immediate actions: First, set hard dollar caps in each provider's billing settings (Anthropic, OpenAI, Cursor, Devin - all have usage limits). Second, implement max-iteration caps in your agent harness so that any agent stops after a defined number of steps. Third, set per-tool quotas (max 50 web searches per session, max 100 file reads) and treat tool-call counts as alert metrics. A simple shell script that polls usage APIs every 5 minutes and kills processes at a threshold ($10 is a reasonable starting point) catches runaway loops within the first hour.

### What is the pricing model for managed AI agents?

There is no unified model. Claude Managed Agents charges model tokens plus $0.08 per session hour plus tool surcharges ($10 per 1,000 web searches). OpenAI Agents SDK bills standard API tokens plus $0.03/GB for sandbox sessions. Devin uses ACUs where one ACU equals roughly 15 agent-minutes. Cursor Background Agents ride on subscriptions with metered overflow. GitHub Copilot charges per-seat with 300 premium requests bundled. Each provider has its own dashboard, its own units, and its own billing cycle - there is no cross-provider cost attribution yet.

### What is FinOps for AI agents?

FinOps (Financial Operations) for AI agents is the practice of monitoring, attributing, and controlling the costs of running autonomous AI systems. It includes unified cost tracking across providers, per-task and per-user attribution, budget alerts, and automated kill switches when spending thresholds are exceeded. The OpenTelemetry trace model provides the foundation - traces, spans, and resource attributes can carry cost data if providers adopt the semantic conventions and teams build enrichment layers that convert tokens and tool calls into dollar figures.

### How much does an AI agent cost per task?

Costs vary dramatically based on task complexity and failure modes. Field reports show Cursor Background Agents averaging $4-5 per "easy" PR. Claude Managed Agents with Opus 4.6 can run $5-25 per session depending on token usage and tool calls. A pathological loop that retries 200 times can easily reach $200-400 in a single overnight session. The unpredictability is the problem - the same task can cost $5 or $50 depending on whether the agent hits an error it cannot escape.

### What is OpenTelemetry and how does it help with agent costs?

OpenTelemetry (OTel) is a vendor-neutral observability standard for traces, metrics, and logs. For AI agents, it provides a way to track every model call, tool invocation, and session as spans within a trace. The GenAI semantic conventions already define attributes like `gen_ai.usage.input_tokens` and `gen_ai.usage.output_tokens`. With OTel tracing enabled (supported by Claude Agent SDK, OpenAI Agents SDK, LangGraph, Vercel AI SDK), you can reconstruct what happened in any session. Cost enrichment layers can then multiply tokens by pricing to attach dollar figures to each span.

### Which AI agent provider is most cost-effective?

It depends on your usage pattern. For high-volume, short tasks, per-seat models like GitHub Copilot may be cheapest. For complex, long-running tasks, token-based pricing with aggressive caching (like OpenAI Agents SDK) can work well. For predictable workloads, ACU-based models like Devin offer cost certainty. The absence of cross-provider attribution makes comparison difficult - the only way to know is to run parallel experiments with cost tracking enabled and measure actual spend per task type.

### How do I track AI agent costs across multiple providers?

Today, you cannot do this from any single dashboard. You must open each provider's billing page, correlate timestamps manually, and sum the costs yourself. Tools like DD Traces are building cross-provider cost attribution using OpenTelemetry spans, but the enrichment layer that converts tokens and tool calls to dollars is still in development. The interim solution is to enable OTel tracing on all agents, send spans to a local collector, and build your own cost lookup table until the tooling matures.


10 CLI Tools Reshaping AI Development in 2026
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
The terminal is the new IDE. In 2026, the best developer CLIs do not just wrap APIs, they host [agents](/blog/what-is-an-ai-coding-agent-2026), stream tokens, sandbox file edits, and plan multi-step work across your repo. An "AI-native" CLI in 2026 has three traits: it understands natural language as a first-class input, it can take action on your machine (files, shell, git, HTTP), and it leans on a frontier model as its runtime brain rather than a scripted state machine.

The list below is the shortlist. Ten CLI tools for AI development that earn a spot on a 2026 developer workstation, drawn from the [full 50-tool directory](https://clis.developersdigest.tech). Install commands are real. Opinions are honest. If you want to build your own, start with the [Building CLIs with TypeScript course](/courses/building-clis).

## Source Trail and Related Guides

CLI tooling changes faster than most blog posts age. Use official project pages for install commands and DevDigest posts for the workflow comparison:

| CLI | Official source | Related DevDigest guide |
|-----|-----------------|-------------------------|
| Claude Code | [Claude Code docs](https://code.claude.com/docs/en/overview) | [Claude Code complete guide](/blog/what-is-claude-code-complete-guide-2026) |
| Codex | [OpenAI Codex repo](https://github.com/openai/codex) and [Codex changelog](https://developers.openai.com/codex/changelog) | [Codex changelog April 2026](/blog/codex-changelog-april-2026) |
| Cursor | [Cursor pricing](https://cursor.com/pricing) and [Cursor docs](https://cursor.com/docs) | [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026) |
| Gemini CLI | [Gemini CLI repo](https://github.com/google-gemini/gemini-cli) | [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) |
| MCP-enabled agents | [MCP docs](https://modelcontextprotocol.io/docs/getting-started/intro) | [Complete MCP server guide](/blog/complete-guide-mcp-servers) |

If you are choosing one primary CLI, read the [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) comparison after this list. The install command is the easy part. The harder question is which loop you want to live in every day.

## 1. Claude Code

**Hook:** The agentic coding CLI that kicked off the terminal-as-IDE wave.

For broader context, pair this with [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) and [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); those companion pieces show where this fits in the wider AI developer workflow.

Anthropic's [Claude Code](https://github.com/anthropics/claude-code) plans, reads, edits, and runs commands across your codebase with permission prompts and tool use built in. It is the AI coding CLI that feels closest to having a senior engineer in your tmux pane. Skills, subagents, hooks, and MCP servers make it extensible in ways that matter for real work.

Reach for it when you want an agent that can actually finish a multi-file task, not just autocomplete a line. If you are choosing between Claude Code and the OpenAI stack, the [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) comparison is the cleaner next read.

```bash
npm install -g @anthropic-ai/claude-code
```

## 2. Codex

**Hook:** [OpenAI](/blog/openai-vs-anthropic-2026)'s answer to Claude Code, open-source and sandboxed.

[Codex](https://github.com/openai/codex) is OpenAI's coding agent for the terminal. It reads and modifies your codebase with sandboxed execution, which means destructive commands need explicit approval. It pairs naturally with GPT-5.x models and is a strong pick if you already live inside the OpenAI ecosystem. For recent product direction, read the [Codex April changelog](/blog/codex-changelog-april-2026).

Reach for it when you want parity with Claude Code on a different model stack, or when open-source and sandboxing are non-negotiable.

```bash
npm install -g @openai/codex
```

## 3. Gemini CLI

**Hook:** Google's free-tier coding agent with a 1M context window.

[Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's terminal agent powered by Gemini models. The generous free tier and million-token context make it a uniquely good fit for very large monorepos, long log files, and "read this whole folder" tasks where other agents need to summarize first.

Reach for it when context length matters more than anything else, or when you want an unmetered daily driver.

```bash
npm install -g @google/gemini-cli
```

## 4. Aider

**Hook:** The OG AI pair programmer that still punches above its weight.

[Aider](https://aider.chat) is a Python CLI that works with any LLM to edit code inside your local git repo. It auto-commits each change with a descriptive message, which turns your git log into a readable audit trail of what the AI touched. It supports repo maps, voice mode, and dozens of models.

Reach for it when you want clean git hygiene by default, or when you want to bring your own model (local Llama, Kimi, [DeepSeek](/blog/deepseek-v4-developer-guide), whatever you have).

```bash
pip install aider-chat
```

## 5. Cursor

**Hook:** The AI-first editor with a surprisingly capable CLI.

[Cursor](https://cursor.com) is best known as the AI code editor, but its `cursor-agent` CLI now runs headless agents from the terminal, opens projects, and triggers background jobs. It is the bridge between GUI-first and CLI-first workflows, and the [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026) comparison explains when that bridge beats a terminal-first loop.

Reach for it when your team lives in [Cursor](/blog/what-is-cursor-ai-code-editor-2026) already and you want scripted agents without leaving the stack.

```bash
brew install --cask cursor
```

## 6. Ollama

**Hook:** One command to run frontier-class local models.

[Ollama](https://ollama.com) is the easiest way to run large language models locally. One command pulls Llama, Mistral, Gemma, Qwen, DeepSeek, and dozens more, with a clean OpenAI-compatible API on `localhost:11434`. It is the foundation of most offline and privacy-first AI coding setups.

Reach for it when you need to run models on your own hardware, whether that is a MacBook, a homelab, or a DGX Spark.

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

## 7. LLM

**Hook:** Simon Willison's swiss-army knife for prompting from the shell.

[LLM](https://llm.datasette.io) is a CLI for running prompts against any provider, with first-class support for plugins, templates, embeddings, and SQLite-backed logs. It is unglamorous and indispensable. You pipe things into `llm`, you pipe things out, and you keep every prompt you ever ran in a queryable database.

Reach for it when you want scriptable, composable AI that plays nicely with Unix pipes and cron jobs. If you need actual prompt content to pipe through it, our [prompt library](/prompts) has a starter set tagged by use case.

```bash
brew install llm
```

## 8. AIChat

**Hook:** One CLI, every major model, with [RAG](/blog/what-is-rag) and sessions built in.

[AIChat](https://github.com/sigoden/aichat) is a Rust CLI that talks to OpenAI, Claude, Gemini, Ollama, and more behind a single unified interface. Roles, sessions, RAG, and function calling are first-class. It is the fastest way to hot-swap models without learning a new command for each provider.

Reach for it when you want to A/B test models for the same prompt, or when you want one tool that survives provider churn.

```bash
brew install aichat
```

## 9. Fabric

**Hook:** Curated prompt patterns turned into Unix commands.

[Fabric](https://github.com/danielmiessler/fabric) is Daniel Miessler's AI CLI that ships with a library of reusable "patterns" for summarizing, extracting, rewriting, and analyzing content. Pipe any text into a pattern like `summarize`, `extract_wisdom`, or `write_essay` and you get structured output tailored to that task.

Reach for it when you want AI that behaves like a Unix tool: deterministic input, deterministic output, composable with everything else on your PATH.

```bash
go install github.com/danielmiessler/fabric@latest
```

## 10. GitHub CLI

**Hook:** Not AI, but the connective tissue every AI agent needs.

[GitHub CLI](https://cli.github.com) is not an AI tool on paper, but in practice it is the most common thing AI agents shell out to. `gh pr create`, `gh issue list`, `gh run watch`. Claude Code, Codex, Aider, and every other agent on this list is more useful when `gh` is installed and authenticated.

Reach for it as the glue between your AI CLI and the rest of your delivery pipeline.

```bash
brew install gh
```

## Honorable mentions worth your attention

A few tools that did not make the top ten but deserve a callout on any best developer CLI 2026 list:

- **Bun** for a single runtime that bundles, tests, and installs faster than anything else in the Node ecosystem.
- **ripgrep** and **fzf** for the fuzzy-search duo every AI agent secretly depends on under the hood.
- **Wrangler** for shipping AI workloads to Cloudflare Workers AI without leaving the terminal.
- **Supabase CLI** for standing up a Postgres, auth, and vector-search backend for your agents in one command.

We also ship a handful of small, opinionated CLIs here at Developers Digest. `dd` for project scaffolding, `hue` for Gumroad-flavored terminal theming, and `skill-builder` for turning working knowledge into reusable Claude Code skills. They are not for everyone, but if you live in this stack they are worth a look.

## Pick two, master them, then expand

The honest advice on AI coding CLIs in 2026 is not to install all ten on day one. Pick a primary agent (Claude Code or Codex), pair it with a model-flexible runner (LLM or AIChat), and add `gh` plus `ripgrep` so your agent can navigate the world. Everything else is additive.

Then, when you hit a job that does not fit, reach for the specialist. Huge codebase? Gemini CLI. Local and offline? Ollama. Need reproducible prompt patterns? Fabric. Want clean git history from your AI? Aider. Need external systems like Postgres, GitHub, or browsers? Add the right [MCP servers](/blog/best-mcp-servers-2026) instead of forcing everything through shell commands.

The full directory of 50+ CLI tools for AI development, filtered by category and ranked by GitHub stars, lives at **[clis.developersdigest.tech](https://clis.developersdigest.tech)**. Bookmark it, search it when you are picking tools for a new project, and come back when the landscape shifts again, because it will.

## Frequently Asked Questions

### What is the best CLI tool for AI coding in 2026?

Claude Code is the most capable agentic coding CLI in 2026. It plans multi-step tasks, reads and edits files across your codebase, runs shell commands with permission prompts, and supports extensibility through skills, subagents, and MCP servers. If you want one tool that can actually finish complex multi-file tasks autonomously, Claude Code is the default choice. Codex from OpenAI is the strongest alternative if you prefer the GPT model family or need open-source sandboxing.

### Should I use Claude Code or Codex?

Choose based on your model preference and ecosystem. Claude Code runs on Anthropic's Claude models and has deeper integration with MCP servers and the skills system. Codex runs on OpenAI's GPT-5.x models and emphasizes sandboxed execution with explicit approval for destructive commands. Both can handle multi-file refactors, test generation, and code review. If you already use Anthropic for other work, Claude Code has less friction. If you are invested in OpenAI, Codex integrates more naturally.

### Can I use AI coding CLIs with local models?

Yes. Ollama makes it trivial to run Llama, Mistral, Qwen, DeepSeek, and other models locally with an OpenAI-compatible API. Aider supports Ollama and other local backends out of the box. AIChat can also connect to Ollama as a provider. For offline or privacy-sensitive work, combine Ollama with one of these model-agnostic CLIs. The trade-off is that local models are generally less capable than frontier models for complex agentic tasks.

### What CLI should I use for very large codebases?

Gemini CLI handles large monorepos better than most alternatives because of its 1 million token context window. Where Claude Code or Codex might need to summarize or chunk files, Gemini CLI can ingest entire directories in a single pass. The generous free tier makes it practical for exploratory work. For extremely large repos, combine Gemini CLI for reading and analysis with Claude Code or Codex for editing.

### How do AI coding CLIs compare to AI code editors like Cursor?

AI code editors like Cursor provide a full IDE experience with inline completions, chat panels, and GUI-based agent controls. AI coding CLIs like Claude Code and Codex run in your terminal and are designed for scripting, automation, and integration with other Unix tools. Many developers use both - the editor for interactive work and the CLI for batch tasks, CI integration, or running agents overnight. Cursor also has a `cursor-agent` CLI that bridges the two worlds.

### What is the difference between LLM and AIChat?

Both LLM and AIChat are model-agnostic CLIs for running prompts from the terminal. LLM (by Simon Willison) emphasizes Unix-style composability, plugins, templates, and SQLite-backed logging of every prompt. AIChat emphasizes a unified interface across providers with built-in roles, sessions, RAG, and function calling. Use LLM if you want to pipe prompts through shell scripts and keep a queryable history. Use AIChat if you want to hot-swap models and need session state or RAG out of the box.

### Do I need MCP servers for AI coding CLIs?

MCP servers are optional but powerful. They let your AI agent connect to databases, browsers, GitHub, Slack, and other external systems through a standardized protocol. Claude Code has first-class MCP support. Without MCP, your agent is limited to file operations and shell commands. With MCP, it can query your Postgres database, open browser tabs, read GitHub issues, and interact with any service that exposes an MCP interface. Start without MCP, then add servers as you hit limitations.

### What is the minimum setup for AI coding from the terminal?

Install Claude Code or Codex as your primary agent, GitHub CLI for repository operations, and ripgrep for fast code search. These three tools cover 90% of AI-assisted coding workflows. Add Ollama if you need local models, and LLM or AIChat if you want scriptable prompts for automation. Everything else is additive based on specific needs - Gemini CLI for huge context, Aider for clean git commits, Fabric for reusable prompt patterns.


How I'm Building 24 AI-Powered Apps in Parallel
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
## One Dev, 24 Subdomains

There are currently 24 apps on the Developers Digest network. Fitness tracker, cron scheduler, video clipper, CLI directory, [MCP](/blog/what-is-mcp) directory, skills marketplace, AI model comparison, overnight agents, agent hub, content calendar, voice tools, and a dozen more. Every one lives on its own subdomain under `developersdigest.tech`.

For the implementation path around this, pair it with [Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook](/blog/claude-code-agent-teams-subagents-2026) and [Why Skills Beat Prompts for Coding Agents in 2026](/blog/why-skills-beat-prompts-for-coding-agents-2026); those guides connect the idea to a shippable TypeScript stack.

One developer. No team. Most are running in production. Some are fully shipped. A lot of them are half working. I want to be honest about that because the interesting thing is not that they all work. The interesting thing is that 24 of them exist at all, and that a single dev can keep pushing them forward in parallel without the whole thing collapsing.

This post is the meta-story. The stack, the pattern, the agent loop, what broke, and the tactical lessons I would give to anyone trying to run a similar portfolio.

## The Stack

Every app uses the same spine so I do not have to think about infrastructure per project:

- **[Next.js](/blog/nextjs-ai-app-stack-2026) 16** with React 19 and the App Router. One mental model for every app.
- **Convex** for the reactive backend. Schemas, server functions, and cron jobs in one place.
- **Clerk** for auth. Drop-in, works everywhere, OAuth providers handled.
- **Drizzle** where I need a relational store instead of Convex. Same schema language across apps.
- **Kimi and Claude Code** as the [coding agents](/blog/what-is-an-ai-coding-agent-2026). Kimi for unlimited volume, Claude Code for the harder refactors.
- **Coolify on Hetzner** for hosting. One box, one Coolify, every app a separate project, Cloudflare pointing each subdomain at the same ingress.

That is it. No Vercel. No AWS. No Kubernetes. No per-app decisions about hosting, auth, or database. The stack is the same every time, so bootstrapping a new app is closer to copy-paste than to architecture.

The reason this matters: when the stack is identical, the agents do not need to relearn anything. Whatever works for one app works for the next.

## The Pattern: Registry + Subdomain Per Sub-Brand

The hub is the `/apps` page on developersdigest.tech. It is driven by a single file, `app/apps/apps-data.ts`, which is the source of truth for every product in the network. Each entry looks like this:

```ts
{
  slug: "fit",
  name: "Fit",
  host: "fit.developersdigest.tech",
  url: "https://fit.developersdigest.tech",
  description: "Log workouts in plain English...",
  category: "SaaS Products",
  badge: "Popular",
  searchKeywords: ["fitness", "habits", "tracking"],
}
```

One row per app. The registry feeds the `/apps` directory, the JSON-LD metadata, the search index, and the hero terminal. Adding a new product is one commit to `apps-data.ts` plus a Cloudflare DNS record. That is the whole onboarding.

Each sub-brand gets its own subdomain because the alternative (everything under one domain) would turn every design and auth decision into a coordination problem. Subdomains give each app its own identity, its own design freedom, its own deploy cadence, and crucially its own blast radius when something breaks.

## The Agent Loop

The loop that keeps 24 apps moving forward without me turning into a tech lead in my own life:

1. **Audit.** One agent per app reads the repo, runs the build, checks what is real versus what is mock, and produces a short status report. The output goes to a shared status file (`APPS-TIGHTEN-STATUS.md`) that I can skim in 60 seconds.
2. **Parallel [subagents](/blog/claude-code-sub-agents).** Based on the audit, I spawn a batch of agents, each scoped to one app and one concrete fix. Kill the fake API key in `dd-cron`. Consolidate magic numbers in `dd-fitness`. Delete the dead `/app` directory in `dd-canvas`. Each agent has one target, one set of files, zero coordination overhead.
3. **Commit.** Each agent commits to its own repo with a scoped message. Small atomic commits, one fix per commit, so anything can be reverted without taking down the rest.
4. **Staggered deploy.** Coolify does not love 10 builds firing at once on a single Hetzner box. So the deploy queue is explicit and ordered. One deploy per iteration. Verify health. Move to the next.

A real slice from this week's status file:

```
iter 1 (cron 73814f48, first run)
- dd-clipper 8fe1af6: mockClips/Transcript/runMockPipeline deleted, empty state honest
- dd-fitness 8452cd7: DEFAULT_TARGETS consolidated across 5 components, tests green

Deploy queue (staggered):
1. contentcal (credit check fix)
2. dd-academy (real streak)
3. dd-cron (fake key gone)
4. dd-content-engine (fake key gone)
5. dd-fitness (rebuild)
6. dd-canvas (rebuild)
```

That is the whole workflow. Audit, fan out, commit, deploy one at a time. The cron runs the loop on its own. I check in, read the status file, approve or redirect.

## What Broke

The honest tier list looks like this:

- **Shipped and working:** Fit, ContentCal, Hue, Voice, AI Models directory, CLI directory, MCP directory. These have real APIs behind them, real data, real flows.
- **Half built:** Cron, Canvas, Academy, Content Engine, Video Clipper, DD Traces, DD Starter, Demos. Mock data is mostly killed, but the core value prop is not fully wired. DD Traces, for example, advertises local OTLP capture. The OTLP receiver is not done yet. That is the gap between the landing page and the product.
- **Scaffolding only:** Overnight Agents, Auto Company, DD Orchestrator, Agent Generator. These have the marketing surface and some plumbing, but not the brain.
- **Missing entirely:** DD Build was on the apps page with no repo behind it. That is a bug. It gets removed or scaffolded from `dd-canvas`.

Why put this in a public post? Because pretending the portfolio is 24-for-24 production apps would be a lie, and the interesting thing is the mechanism, not the polish. Half-built is the natural state of a portfolio that is growing faster than any single dev can finish individual products. The loop is designed to close those gaps over time, not to avoid ever having them.

The credibility move is saying "here is what is real, here is what is not, here is the queue." That beats a glossy launch page that falls over on first click.

## Top Lessons

Seven tactical takeaways from running this loop for the past few months:

### 1. Mock data is a commitment device

Shipping an app with `mockClips`, `mockTranscript`, and `runMockPipeline` feels fast. It is not. It is a landmine. Every mock is a lie you will have to explain to a user who clicked something and got nothing back. Killing mocks early forces you to either wire the real thing or ship an honest empty state. Both are better than fake data.

### 2. Staggered deploys prevent OOMs

A single Hetzner box running Coolify cannot build 10 Next.js 16 apps at the same time without tipping over. I learned this by watching my build queue return 500s while `docker builder prune -f` crawled. The fix is operational, not architectural. One deploy per iteration. Verify. Move on.

### 3. One audit agent per domain beats one big one

I tried a single "audit the portfolio" agent. It produced beautiful generic slop. Switching to one agent per app, each reading only that app's repo, produced actionable status reports that fit on a page. Narrow scope, narrow context, narrow output.

### 4. Registry-driven directories scale better than per-route pages

Every app in the network is one row in `apps-data.ts`. That single file drives the `/apps` page, search, metadata, and terminal navigation. When a new app ships, it is one commit. When an app gets renamed, it is one commit. There are no scattered references to update.

### 5. Identical stack everywhere is a productivity multiplier

Next.js 16 plus Convex plus Clerk plus Coolify is the same every time. The agents do not waste context figuring out which auth system this app uses or how this one deploys. The marginal cost of a new app is the feature work, not the infrastructure tax.

### 6. Use the cheap unlimited agent for volume, the expensive one for judgment

Kimi handles the high-volume grunt work. Killing mocks, renaming files, fixing lint, writing boilerplate. Claude Code gets the tasks that require judgment. Refactors that cross files. Decisions about architecture. Anywhere the wrong call costs a day of rework.

### 7. Half-built in public beats polished in private

The temptation is to hide the half-working apps until they are done. The problem is they are never done. There is always another feature, always another edge case. Publishing the registry and the status file publicly forces the work to move forward because the gap is visible. "DD Build has no repo" is a lot harder to ignore when the row is live on the `/apps` page.

## The CLI That Runs It All

The entire loop is driven by the `dd` CLI. One command to scaffold a new app (`dd new`), one to audit (`dd audit`), one to deploy (`dd deploy`). Each command is a thin wrapper over the same agent and infrastructure stack, but it turns the workflow into muscle memory.

If you want to see the apps, the registry is live at [/apps](/apps). If you want to see the CLI that glues the network together, it is at [cli.developersdigest.tech](https://cli.developersdigest.tech). And if you want the longer writeup of how the main site was built, the [case study](/blog/case-study-building-dd-with-ai) has the receipts.

## Takeaway

One developer running 24 apps works because the stack is identical, the registry is one file, the loop is automated, and the honesty is public. The agents do the grunt work. The CLI does the orchestration. The status file keeps me in the loop without making me the bottleneck.

It is not that any of these apps are individually revolutionary. They are not. The interesting thing is that 24 of them exist on the same spine, maintained by one person, with a system that lets them keep improving in parallel without any single app starving the others.

That is the playbook. The portfolio is the product.

## Frequently Asked Questions

### How can one developer manage 24 apps at once?

By using the same stack everywhere and automating the audit-fix-deploy loop. When every app uses Next.js 16, Convex, Clerk, and Coolify, the agents do not waste context learning infrastructure per project. The loop runs on its own: one audit agent per app produces a status file, parallel subagents fix specific issues, and staggered deploys prevent build queue overload. The developer reviews and redirects instead of doing the grunt work.

### What is the best stack for building multiple AI apps in parallel?

For a single developer running many apps, the stack should be identical everywhere. The recommended combination is Next.js 16 with React 19 and the App Router, Convex for the reactive backend, Clerk for auth, and Coolify on Hetzner for hosting. This removes per-app infrastructure decisions and lets coding agents reuse everything they learn from one project on the next.

### How do you deploy 24 apps from one server without it crashing?

Staggered deploys. A single Hetzner box running Coolify cannot build multiple Next.js 16 apps simultaneously without running out of memory. The fix is operational: deploy one app per iteration, verify health, then move to the next. The deploy queue is explicit and ordered in the workflow, not left to chance.

### Should I use Claude Code or Kimi for building apps?

Use both for different tasks. Kimi handles high-volume grunt work - killing mocks, renaming files, fixing lint, writing boilerplate - because it offers unlimited usage. Claude Code handles tasks that require judgment - refactors that cross files, architectural decisions, anything where the wrong call costs a day of rework. Match the agent to the complexity of the task.

### What is a registry-driven app directory?

A single file that is the source of truth for every product in your network. Each app is one row with its slug, name, host, URL, description, and category. That file drives the apps page, search index, JSON-LD metadata, and terminal navigation. Adding a new app is one commit to the registry file plus a DNS record. No scattered references to update.

### How do you handle half-built apps in a portfolio?

Ship them with honest empty states instead of mock data. Mock data is a lie that will break user trust on first click. An honest empty state says "this feature is coming" and lets users understand what is real. Publishing the status file publicly forces progress because the gap between promise and reality is visible.

### What does an AI agent audit loop look like?

One agent per app reads the repo, runs the build, and produces a short status report identifying what is real versus mock. The outputs go to a shared status file. Based on the audit, parallel subagents spawn to fix specific issues - each scoped to one app and one concrete fix. Every agent commits to its own repo with atomic, scoped messages. The loop runs automatically and surfaces only the decisions that need human input.

### How long does it take to add a new app to the portfolio?

Minutes. Copy the stack from an existing app, add one row to the registry file with the app's metadata, create a Cloudflare DNS record pointing the subdomain to the same ingress, and deploy. The identical stack means no infrastructure decisions per project. The registry-driven directory means no pages to update. The marginal cost of a new app is the feature work, not the setup.


Claude Code vs Codex vs Cursor vs OpenCode: Which Agent Ships More Code?
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
I use all four of these daily. Not as demos. As the tools that close PRs, fix regressions, and push code to production on live apps. So when people ask which one "wins," the honest answer is: they each have a lane, and pretending otherwise wastes your subscription. If you are still separating autocomplete from real agent work, start with [what an AI coding agent is](/blog/what-is-an-ai-coding-agent-2026) before this shoot-out.

Here is the short version for anyone skimming, then the deeper cuts on install, what each agent is actually good at, where each one fumbles, and how to pick.

## Shoot-out Table

| Agent | Runtime | Best Model | Pricing Model | Where It Wins |
|-------|---------|------------|---------------|---------------|
| Claude Code | Local CLI + subagents | Claude Opus 4.6 / Sonnet 4.6 | Subscription (Pro / Max) or API | Long coherent sessions, refactors, skill-driven workflows |
| Codex CLI | Local CLI + cloud runners | GPT-5.3-Codex / GPT-5.4 | ChatGPT plan or API | Parallel agent fleets, fast iteration, cloud-native work |
| Cursor Agent | IDE-integrated + CLI | Multi-model (Claude, GPT-5.x, Gemini) | Pro ($20/mo) or Business | Tight edit loops inside an IDE, model switching |
| OpenCode | Local CLI, open source | Bring-your-own (any provider) | Free (your API keys) | Self-hosted, model-agnostic, no vendor lock-in |

For the OpenAI side of the agent stack, read [Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook](/blog/claude-code-agent-teams-subagents-2026) with [Why Skills Beat Prompts for Coding Agents in 2026](/blog/why-skills-beat-prompts-for-coding-agents-2026); that gives the product and workflow context behind this update.

Pricing context: current frontier model floors on `models.json` from `dd-subagents` put Claude Opus 4.6 at `$10/M tokens`, [GPT-5.3-Codex](/blog/gpt-5-codex) at `$4.81/M`, GPT-5.4 at `$5.63/M`, and `GLM-5` at `$1.55/M`. If you run OpenCode against Kimi K2.5 at `$1.20/M`, you can cover a *lot* of tokens for the price of one Max plan. Whether that's smart depends on what you're building.

## Source Trail and Companion Reads

Use this post as the opinionated field guide, then verify the moving parts against the primary sources:

| Topic | Primary source | DevDigest context |
|-------|----------------|-------------------|
| Claude Code capabilities | [Claude Code overview](https://code.claude.com/docs/en/overview) | [Claude Code complete guide](/blog/what-is-claude-code-complete-guide-2026), [skills guide](/blog/why-skills-beat-prompts-for-coding-agents-2026) |
| Codex changes | [Codex changelog](https://developers.openai.com/codex/changelog) | [Codex April changelog](/blog/codex-changelog-april-2026), [Codex guide](/blog/openai-codex-guide) |
| Cursor plan shape | [Cursor pricing](https://cursor.com/pricing) | [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026), [Cursor 2.0 deep dive](/blog/cursor-2-0-composer-deep-dive) |
| Budget planning | [OpenAI Codex plan docs](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) | [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison), [Q2 pricing update](/blog/ai-coding-tools-pricing-q2-2026) |

That gives the reader three paths out of this comparison: validate official plan details, go deeper on a specific tool, or jump sideways into the broader [pricing](/blog/ai-coding-tools-pricing-2026) matrix.

Now the honest breakdown.

## Claude Code

### Install

```bash
npm install -g @anthropic-ai/claude-code
claude
```

Sign in with your [Anthropic](/blog/anthropic-vs-openai-developer-experience) account or set `ANTHROPIC_API_KEY`. A Pro or Max plan routes through subscription quota instead of per-token API billing, which matters at volume.

### What it's great at

Long-horizon sessions. [Claude Code](/blog/what-is-claude-code-complete-guide-2026) is the only agent in this lineup where I can run a multi-hour refactor across 40 files and trust the context to stay coherent. [Subagents](/blog/claude-code-sub-agents), hooks, and project-level `CLAUDE.md` rules let me shape behavior without retraining the model. The [skill system](/blog/why-skills-beat-prompts-for-coding-agents-2026) (`~/.claude/skills/`) lets me drop in reusable workflows like `/handoff`, `/qa`, or `/devdigest:ship-product` that fire the right sequence of tools without re-prompting.

The [tool use](/blog/tool-use-claude-api-production-patterns) discipline is the differentiator. Claude reads before it writes, proposes before it edits, and will stop to ask rather than hallucinate a file path. That's boring in a demo and priceless at 2am debugging a deploy.

### What it fumbles

Parallelism. Claude Code runs one main loop at a time. Subagents help, but if you want to spin up 10 agents each building a separate feature, you'll feel the single-session ceiling. Also: rate limits on Max plans are real. Shipping heavy on Opus 4.6 will eventually hit a reset window and you'll be stuck.

Model switching is also awkward. You can swap between Opus and Sonnet, but you can't easily swap in GPT-5.4 or Gemini for a second opinion without a wrapper.

### Pricing

Pro is `$20/mo`, Max is `$100` or `$200/mo`, API is pay-per-token. At production volume the `$200` Max plan pays for itself in a week compared to raw API.

### Best use case

Serious builders doing deep work on a single complex codebase. If you're refactoring, architecting, or running a "one human, one codebase, ship daily" workflow, this is the pick.

## Codex CLI

### Install

```bash
npm install -g @openai/codex
codex
```

Sign in with your ChatGPT account. Plus, Pro, and Business plans include Codex usage; API keys work too. The Codex desktop app launched on macOS in February 2026 and Windows a month later, but the CLI is still the workhorse.

### What it's great at

Parallel fleets. [Codex](/blog/openai-codex-guide) was built from the jump around the idea that the bottleneck isn't model capability, it's human supervision of many concurrent agents. Worktree isolation, cloud runners, and the `codex exec` headless mode make it the best option when you want to fan out work across branches or machines. The [April Codex changelog](/blog/codex-changelog-april-2026) matters because it pushes that same idea into goals, browser verification, and safer approval workflows.

GPT-5.3-Codex is *fast*. At `89 tokens/sec` versus Claude's `44-46 tokens/sec`, you feel the difference on iterative loops where you're waiting on a diff to land. For plumbing work, test generation, or scripting, Codex is often done before Claude has finished reading.

### What it fumbles

Depth on long sessions. Codex will cheerfully edit a file it hasn't read, and on hour three of a complex refactor it starts drifting. Hooks and tool discipline are less mature than Claude Code's. For a greenfield script, no problem. For surgery on a 50k-line app, you feel it.

The "cloud runner" story is also uneven. When it works, it's magic. When it doesn't, debugging why the runner can't see your repo is its own side quest.

### Pricing

ChatGPT Plus is `$20/mo`, Pro is `$200/mo`, Business/Enterprise are seat-based. API pricing on GPT-5.3-Codex is `$4.81/M tokens`, GPT-5.4 is `$5.63/M`.

### Best use case

Parallel work. If your workflow is "spawn five agents, each takes a ticket, I review PRs," Codex is built for that.

## Cursor Agent

### Install

Download the IDE from `cursor.com`, or use the CLI:

```bash
curl -fsSL https://cursor.com/install | bash
cursor-agent -p "your prompt"
```

### What it's great at

The IDE loop. [Cursor](/blog/what-is-cursor-ai-code-editor-2026)'s advantage is not the agent itself, it's that the agent lives inside the editor where you're already reading the code. Tab completion, inline diffs, and "agent mode" in the sidebar mean you're never copy-pasting between a terminal and a file. For front-end work especially, this is the tightest feedback loop in the lineup, which is why the dedicated [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026) comparison is more useful than a pure model benchmark.

Model switching is the other win. You pick Claude Sonnet for one task, swap to GPT-5.4 for another, drop down to Gemini 3.1 for a cheap pass. The Pro plan at `$20/mo` includes a generous pool of "fast" requests across models.

### What it fumbles

Agent depth. Cursor's agent mode is improving fast, but it still behaves more like "smart autocomplete with a plan" than a true autonomous loop. It will ask for approval more often than Claude Code and lose context on longer runs. Headless CLI mode (`cursor-agent -p`) works but feels like an afterthought next to Claude or Codex native CLIs.

### Pricing

Pro is `$20/mo`, Business is `$40/user/mo`. Request quotas reset monthly and heavy users will hit them.

### Best use case

Editor-native work. If you live in your IDE and want an agent that augments your typing rather than replacing your session, Cursor is the fit.

## OpenCode

### Install

```bash
curl -fsSL https://opencode.ai/install | bash
opencode
```

Set `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or any compatible endpoint in the config. It will pick up local Ollama, MiniMax, or OpenRouter without ceremony.

### What it's great at

No lock-in. OpenCode is open source, model-agnostic, and self-hosted. You point it at whatever provider you want. Running Claude Sonnet one day, GLM-5 the next, Kimi K2.5 on the third. The UI is a respectable TUI that mirrors what you'd get from Claude Code or Codex without the subscription.

For teams with sensitive code that can't touch a vendor API, OpenCode plus a local model via Ollama is the only option in this lineup that runs fully offline. DGX Spark or a decent local GPU and you have an agent that never phones home.

### What it fumbles

Polish and skills. OpenCode gives you the loop, but you assemble the rest. No equivalent of Claude skills, no hook system as mature, no desktop app supervising a fleet. If you want "it just works," this isn't it. You're trading convenience for control.

Model quality is also your problem. Point it at a weak model and you'll get weak output, and no amount of prompt engineering fixes a 35-intelligence model trying to refactor a Next.js app.

### Pricing

Free. You pay for model API usage directly. At `$1.20-1.55/M tokens` on GLM-5 or Kimi K2.5, heavy usage can run under `$20/mo` total.

### Best use case

Tinkerers, self-hosters, and teams that refuse to be locked into a single vendor. Also a great third agent for when Claude and Codex are both rate-limited.

## How to Pick

If you're shipping one product and want the deepest single-agent experience, Claude Code with a Max plan.

If your bottleneck is parallelism, you want more tickets closed per day, Codex CLI.

If you live in an IDE and want the agent there with you, Cursor.

If you hate lock-in, want to run local models, or just want to see how the sausage is made, OpenCode.

The real pro move: run two of them. My daily setup is Claude Code as the primary loop and Codex CLI for parallel side-quests. They complement more than they compete.

## Compare the Models Powering These Agents

Every agent above is only as good as the model inside it. I built a comparison tool that tracks all 208 frontier models by quality score, speed, cost, and context window. Filter by "AI Coding" to see how Claude Opus 4.6, GPT-5.3-Codex, Gemini 3.1 Pro, and the open-weight alternatives actually stack up.

Head to [subagent.developersdigest.tech](https://subagent.developersdigest.tech) for the live leaderboard, cost calculator, and task-based recommendations. Pick the model. Then pick the agent. In that order.

## FAQ

### Which AI coding agent should I use as a beginner?

Start with Claude Code. The tool use discipline - reading files before editing, proposing changes before applying them, stopping to ask clarifying questions - makes it the most forgiving for developers learning how to work with AI agents. The skill system also provides pre-built workflows so you spend less time prompting and more time shipping. Cursor is the second choice if you prefer staying inside an IDE rather than working in a terminal.

### Can I use Claude Code, Codex, Cursor, and OpenCode together?

Yes, and many developers do exactly this. A common pattern is running Claude Code as your primary agent for deep, context-heavy work on a single codebase, then using Codex CLI to parallelize side tasks across branches. OpenCode serves as a fallback when both are rate-limited. The agents don't conflict - they're separate processes with separate context windows. The cost adds up, but the productivity gain often justifies running two subscriptions.

### What is the difference between Cursor and Claude Code?

Cursor is an IDE with an integrated agent - the agent lives inside your editor and augments your typing with completions and diffs. Claude Code is a standalone CLI agent that runs in your terminal and operates more autonomously, making multi-file changes without constant approval. Cursor is tighter for single-file edit loops. Claude Code is deeper for refactors spanning dozens of files. Different tools for different workflows, not direct competitors.

### How much does it cost to use AI coding agents?

Subscription tiers range from $20/mo (Cursor Pro, Claude Code Pro, ChatGPT Plus for Codex) to $200/mo (Claude Code Max, ChatGPT Pro). OpenCode is free - you pay only for API usage, which can run under $20/mo on budget models like GLM-5 or Kimi K2.5. Heavy production usage on a Max plan often costs less than raw API billing would. For a detailed breakdown, see our [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison).

### Which agent is best for parallel development with multiple tasks?

Codex CLI. It was designed around parallel agent fleets from the beginning. Worktree isolation, cloud runners, and headless execution mode (`codex exec`) let you spin up multiple agents working on separate features simultaneously. Claude Code can use subagents but runs one main loop at a time. Cursor and OpenCode are primarily single-session tools. If your workflow involves closing multiple tickets per day with parallel agents, Codex is purpose-built for it.

### Is OpenCode as good as Claude Code or Codex?

OpenCode provides the same core agent loop but with less polish. You get model-agnostic flexibility and full self-hosting capability, but no equivalent of Claude skills, fewer hooks, and no desktop supervisor. The quality of output depends entirely on which model you point it at. A strong model like Claude Sonnet or GPT-5.4 through OpenCode performs comparably to the native agents. A weak local model will underperform significantly. OpenCode is best for tinkerers who value control over convenience.

### Which AI coding agent is fastest?

Codex with GPT-5.3-Codex produces output at around 89 tokens per second versus Claude Code at 44-46 tokens/sec. For iterative loops where you're waiting on diffs to land, the speed difference is noticeable. Claude Code compensates with better depth on long sessions - it maintains coherent context across multi-hour refactors where Codex tends to drift. Speed matters most for quick plumbing tasks. Depth matters more for complex architectural changes.

### Can I run AI coding agents locally without internet?

Only OpenCode supports fully offline operation. Point it at a local model running through Ollama on a DGX Spark or capable GPU and you have an agent that never phones home. This is the only option in this lineup for teams with sensitive code that cannot touch vendor APIs. Claude Code, Codex, and Cursor all require cloud API connections to function.


How to Write a CLAUDE.md: The Complete 2026 Guide
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
Every [Claude Code](/blog/what-is-claude-code-complete-guide-2026) project has a `CLAUDE.md`. Most of them are bad. They read like a new hire handbook written by someone who has never onboarded a new hire - paragraphs of philosophy, vague intentions, promises about the roadmap. The agent reads the file, learns nothing actionable, and proceeds to guess. You get mediocre code. You blame the model.

The irony is that `CLAUDE.md` is the highest-leverage file in any repo you ship with Claude Code. It is the difference between a session where the agent knows which package manager you use, which files are sacred, and which commit conventions to follow - and a session where it reinvents your stack from scratch every turn. A good `CLAUDE.md` changes your shipping velocity. Here is what goes in one.

## What CLAUDE.md actually is

`CLAUDE.md` is a plain markdown file Claude Code reads on load. There is no schema, no required sections, no validator. The agent ingests it into the system prompt and treats it as persistent project memory for every message in the session.

For the design side of the same problem, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) with [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

It lives in three places, in order of priority:

1. **Project root** (`./CLAUDE.md`) - the repo-specific rules that ship with the code.
2. **Subdirectories** (`./packages/web/CLAUDE.md`) - scoped context the agent loads when it starts working inside that directory.
3. **User global** (`~/.claude/CLAUDE.md`) - your personal defaults across every project.

All three get merged. The project file wins ties. You can also link out to other files using the `@` syntax - `@AGENTS.md` at the top of a `CLAUDE.md` will inline the contents of `AGENTS.md`. This matters later.

The file is not a prompt. It is an onboarding doc for a new engineer who knows your language but has never seen your codebase. Write it that way.

## The seven sections every CLAUDE.md should have

### 1. Stack and tooling

One paragraph or a table. Framework, language, database, deployment target, package manager. Include version numbers where they matter (`[Next.js](/blog/nextjs-ai-app-stack-2026) 16`, `React 19`, `Tailwind v4`). The agent will pick the wrong APIs if you leave this off. One rule: if you use `pnpm` and the agent runs `npm install`, your lockfile is now poisoned. Say it once, at the top. Example from a real `dd-fitness/CLAUDE.md`:

```
Next.js 16 + React 19 + TypeScript 5.9. Drizzle ORM on Neon PostgreSQL.
Clerk v7 for auth. Tailwind CSS v4. Vitest for tests. Zod for validation.
Always use pnpm, never npm or yarn.
```

### 2. Hard rules

The things that never happen, with reasons. This is the section that prevents the most damage. Do not phrase them as preferences. Phrase them as laws. "No em dashes anywhere in code, content, or comments - use regular dashes with spaces." "No pink on cream - contrast fails." "No pushing without explicit approval." The reason matters because Claude will reason around a rule it does not understand. It will not reason around a rule it knows is load-bearing.

### 3. File structure

A directory tree with one-line annotations. Not the full tree - the routes that matter. Where pages live, where components live, where content lives, where the backend lives. The agent navigates faster when you tell it where things are than when it has to glob and grep. Fifteen lines here saves ten tool calls per session.

### 4. Conventions

Commit style, PR flow, test framework, linting rules, naming patterns. "Lowercase commit messages." "One feature per PR." "Commit after every meaningful change, do not batch up work." "Tests in `src/__tests__/`, mock `@/lib/auth` for API route tests." This is the glue between the agent's output and your team's (or your own) review process. Without it, every PR needs cosmetic cleanup.

### 5. Common tasks

Step-by-step recipes for the things you do constantly. Add a blog post. Add a new page. Add a new tool. Bump a dependency. Include file paths. Include frontmatter templates. Include the verification step. This section is where velocity gets made - when the agent can follow a four-line recipe instead of asking five questions, you save a whole context window per task.

### 6. Context pointers

Links out to related files, skills, and repos. `@AGENTS.md`. `See GUMROAD-DESIGN-SYSTEM.md for full reference.` `Source of truth for commands lives at ~/Developer/devdigest-cli/README.md.` Claude Code will follow these. You do not have to inline every design token and API contract - you just have to point.

### 7. Deployment

How the code gets to production. Which env vars are required. What the CI gates are. Whether pushing triggers a deploy or whether someone clicks a button. Which domain and what host. This is the section most people skip, and it is the reason agents write env-var-dependent code that crashes at build time. Spell it out: "Coolify auto-deploys on push to main via webhook. Set `DATABASE_URL`, `CLERK_SECRET_KEY`, `KIMI_API_KEY` in Coolify UI before first deploy."

## Examples, not abstractions

Here is a real hard-rules block from a shipped project:

```markdown
## CRITICAL RULES

**No private business info on site.** Never include sponsor deal amounts,
revenue figures, agency names, contract details, or internal business
metrics in any public content.

**No emojis, no gradients.** Gumroad design system uses solid colors, pill
buttons, offset-layer cards.

**No pink on cream.** Pink (#FF90E8) on cream (#F4F4F0) has terrible
contrast. Pink only on white or black backgrounds.

**No em dashes.** Never use em dashes anywhere in the codebase - code,
content, comments, markdown. Use regular dashes with spaces instead.
```

Four rules. Each has a reason. The agent now refuses to commit a change that violates any of them, and tells you why. Zero philosophy, zero room for interpretation.

Here is a real common-tasks block:

```markdown
**"Add a blog post about X":**
1. Research the topic (web search or /devdigest:research)
2. Write content/blog/{slug}.md with proper frontmatter
3. Generate hero image at public/images/blog/{slug}/hero.webp
4. Verify it appears in blog listing and search

**"Add a new tool":**
1. Add to tools[] in lib/tools.ts
2. Auto-appears in /tools listing, search, and terminal
```

Six lines. Covers ninety percent of the recurring work on that repo. When someone says "write a post about Opus 4.7," the agent does not ask where blog posts live, what the frontmatter looks like, whether to add it to search, or where images go. It just ships.

## What to leave out

`CLAUDE.md` is not a journal. It is not a changelog. It is not the place for decisions you are still making, features you might ship, meeting notes, or team history. The rule is simple: if the information rots, it does not belong in `CLAUDE.md`.

Cut these:

- **Roadmap and "future work" sections.** They age out in a week. Keep them in `TODO.md` or an issue tracker.
- **Rationale for past decisions.** Write an ADR. Link to it. Do not inline two paragraphs about why you picked Postgres.
- **Team history, tribal knowledge, inside jokes.** The agent does not have context for any of it and will misinterpret.
- **Anything speculative.** "We might add GraphQL later" teaches the agent to write speculative code. Delete it.
- **Style guides longer than a paragraph.** Move them to `[DESIGN.md](/blog/design-md-for-ai-agents)` and reference with a link.
- **Every edge case you have ever hit.** Keep the top five. The long tail goes in code comments where it belongs.

The test: open your `CLAUDE.md` six months from now. Every line should still be true. If a line might not be, delete it now.

## Advanced patterns

**Per-subdirectory CLAUDE.md.** In a monorepo, put a short `CLAUDE.md` in each package. Claude Code loads the subdir file when it starts working in that directory and merges it with the root file. This keeps the root file focused on project-wide rules and lets each package carry its own commands and conventions. Example: `packages/web/CLAUDE.md` says "Next.js 16, use pnpm, tests with vitest." `packages/api/CLAUDE.md` says "Fastify 5, use bun, tests with node:test." Root file says "monorepo with pnpm workspaces, push to main deploys both apps."

**AGENTS.md layering.** If you work across Claude Code and other agents (Codex, [Cursor](/blog/what-is-cursor-ai-code-editor-2026), Droid), write shared context in `AGENTS.md` and pull it into `CLAUDE.md` with `@AGENTS.md` at the top. That way a single source of truth covers every harness. One real example from `dd-devdigest-site/AGENTS.md`: a three-line note about Next.js 16 breaking changes, reused across every agent that touches the repo.

**Link out to voice files.** For content and marketing repos, keep `SOUL.md` (about the user) and `brand-voice.md` (tone, banned language) alongside `CLAUDE.md`. The main file stays short, the voice files carry the opinionated content. Reference them - do not inline them.

**Progressive disclosure via skills.** Skills are markdown files with YAML frontmatter that Claude loads on demand when a trigger matches. If a workflow is too detailed for `CLAUDE.md` - a multi-step deployment, a content production pipeline, a QA audit routine - write a skill. Point to the skill from `CLAUDE.md` with one line. The agent loads the detail only when it needs it, which keeps your context window clean.

**Commit hooks that enforce rules.** A `PreToolUse` hook in `settings.json` can block a Write that violates a rule. This is belt and suspenders - the rule goes in `CLAUDE.md` so the agent knows, and in the hook so it cannot cheat. Example: a hook that blocks any write containing an em dash.

## The meta rule: one glance

Your `CLAUDE.md` should fit on one screen. Scroll once, maybe. If it is over 300 lines, you have two problems: it is not being read fully, and you are inlining content that belongs elsewhere.

When it gets too long:

- Split design details into `DESIGN.md`. Link from `CLAUDE.md`.
- Split workflows into skills under `.claude/skills/`. Reference by name.
- Split deploy steps into `DEPLOY.md`. Link.
- Split per-package rules into subdirectory `CLAUDE.md` files.
- Move "rationale" and "history" out entirely.

The goal is a file the agent can absorb in one pass and a file you can re-read in thirty seconds to remember why you made every choice. Across 24 shipped apps, the pattern that wins is the short one. Short, opinionated, example-driven, and updated every time you catch yourself answering the same question twice in a session.

## The tools that help

- The [dd CLI](https://devdigest.tech) ships with a `/init` skill that scans your repo and drafts a `CLAUDE.md` with the right stack, file structure, and common tasks pre-filled. Works on any Node, Python, Go, or Rust project.
- The [CLAUDE.md generator](/claudemd-generator) is a web tool if you do not want to install anything - paste your stack and rules, get a formatted file back.
- The [Skill Builder](https://skill.developersdigest.tech) turns long workflows into reusable skills so your `CLAUDE.md` stays short.

Write your `CLAUDE.md` like you are writing an onboarding doc for an engineer who starts tomorrow, reads once, and then ships for a year. That is exactly what you are doing.

## FAQ

### What is CLAUDE.md?

CLAUDE.md is a plain markdown file that Claude Code reads on startup to understand your project. It acts as persistent project memory - containing your stack details, hard rules, file structure, conventions, and common tasks. The agent ingests it into the system prompt and uses it for every message in the session. Think of it as an onboarding doc for a new engineer who knows your language but has never seen your codebase.

### Where does CLAUDE.md go?

CLAUDE.md can live in three places, in priority order: the project root (`./CLAUDE.md`) for repo-specific rules, subdirectories (`./packages/web/CLAUDE.md`) for scoped context, and your user global (`~/.claude/CLAUDE.md`) for personal defaults across all projects. All three get merged, with the project file winning ties.

### What are the essential sections in a CLAUDE.md?

Every effective CLAUDE.md should have seven sections: (1) Stack and tooling - framework, language, database, package manager with versions; (2) Hard rules - absolute constraints with reasons; (3) File structure - annotated directory tree of important paths; (4) Conventions - commit style, PR flow, naming patterns; (5) Common tasks - step-by-step recipes for recurring work; (6) Context pointers - links to design systems, related docs; (7) Deployment - how code gets to production, required env vars.

### How long should CLAUDE.md be?

Your CLAUDE.md should fit on one screen, maybe with one scroll. If it exceeds 300 lines, split content into linked files: design details into DESIGN.md, workflows into skills, deploy steps into DEPLOY.md, per-package rules into subdirectory CLAUDE.md files. The goal is a file the agent can absorb in one pass and you can re-read in 30 seconds.

### What should I NOT include in CLAUDE.md?

Cut anything that rots: roadmaps and future work (put in TODO.md), rationale for past decisions (write ADRs), team history and tribal knowledge, speculative features, style guides longer than a paragraph (move to DESIGN.md), and exhaustive edge cases (keep top five, rest goes in code comments). If a line might not be true in six months, delete it now.

### How do I use CLAUDE.md with other AI agents?

Create an AGENTS.md file with shared context that works across Claude Code, Codex, Cursor, and other tools. Pull it into CLAUDE.md using `@AGENTS.md` at the top - this inlines the contents. Keep agent-specific rules in CLAUDE.md itself, shared project context in AGENTS.md.

### How do I handle CLAUDE.md in a monorepo?

Put a short CLAUDE.md in each package directory. Claude Code loads the subdirectory file when working in that directory and merges it with the root file. Root file covers project-wide rules (monorepo structure, workspace commands). Package files cover local rules (framework, test runner, package manager). Example: root says "pnpm workspaces, push deploys both apps" while packages/web says "Next.js 16, vitest tests" and packages/api says "Fastify 5, bun runtime."

### How do I write hard rules that Claude actually follows?

Phrase rules as laws, not preferences. Include the reason - Claude will reason around rules it does not understand but respects rules it knows are load-bearing. Example: "No pink on cream - contrast fails" works better than "Prefer not using pink on cream backgrounds." Keep rules concrete and actionable. For enforcement, combine CLAUDE.md rules with PreToolUse hooks that block violations.


What Are Claude Code Skills? A Complete Beginner Guide
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
## The Shape of the Problem

You sit down, open [Claude Code](/blog/what-is-claude-code-complete-guide-2026), and start a new session. You paste the same six-step checklist you pasted yesterday. "Run the test suite, then lint, then bump the version, then tag the commit, then push, then open the deploy URL." The model nods, does it, and the context window closes. Tomorrow, you will paste it again.

For the design side of the same problem, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) with [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

This is the loop skills break.

A skill is a folder with a `SKILL.md` file that Claude Code loads when it is relevant. You write the playbook once. Claude uses it whenever the task matches, or you call it directly with `/skill-name`. The full instructions only enter context when they are actually needed, so you can have fifty skills installed and pay almost nothing in tokens until one of them fires.

This guide walks through what skills are, the exact `SKILL.md` schema [Anthropic](/blog/anthropic-vs-openai-developer-experience) documents, where skills live on disk, how invocation actually works, and how to write your first one. If you have not installed Claude Code yet, start with the [Getting Started guide](/guides/claude-code-getting-started). Everything here is cross-checked against the Claude Code and Agent Skills documentation at the time of writing.

## What Is a Skill, Exactly

From the official Claude Code docs: "Skills extend what Claude can do. Create a `SKILL.md` file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with `/skill-name`."

That single sentence captures the two invocation modes. A skill is not a plugin, not an [MCP server](/blog/complete-guide-mcp-servers), and not a hook. It is a filesystem-based unit of procedural knowledge that Claude can discover and load on demand.

The docs are explicit about when to reach for one: "Create a skill when you keep pasting the same playbook, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material [costs](/blog/ai-coding-tools-pricing-comparison) almost nothing until you need it."

That last sentence is the load-bearing one. `CLAUDE.md` content is always in context. A skill is a pointer in context that gets expanded only on use. Anthropic calls this pattern **progressive disclosure**: Level 1 is metadata (always loaded, roughly 100 tokens per skill), Level 2 is the skill body (loaded only when invoked, budgeted under 5k tokens), and Level 3 is bundled reference files and scripts (loaded only when referenced, effectively unlimited). The breakdown comes straight from the Agent Skills overview.

## Agent Skills vs Claude Code Skills

There is real confusion here, so let us pin it down.

**Agent Skills** is the open standard, originally developed by Anthropic and adopted across the industry. The format specification lives at `agentskills.io`. A skill is a folder with a `SKILL.md` file containing YAML frontmatter and markdown instructions. GitHub Copilot, Cursor, OpenCode, Goose, Codex, Gemini CLI, and many others all speak this format.

**Claude Code Skills** are Agent Skills running inside the Claude Code CLI. The Claude Code docs are explicit: "Claude Code skills follow the Agent Skills open standard, which works across multiple AI tools. Claude Code extends the standard with additional features like invocation control, subagent execution, and dynamic context injection."

**Agent Skills via the Claude API** is a third surface. Here, skills run inside Anthropic's code execution container. The API exposes pre-built skills (`pptx`, `xlsx`, `docx`, `pdf`) and custom skills uploaded through the `/v1/skills` endpoints. Per the docs, API skills require three beta headers: `code-execution-2025-08-25`, `skills-2025-10-02`, and `files-api-2025-04-14`. Claude.ai exposes the same capability through its settings UI.

The file format is the same everywhere. The runtime is not. API skills have no network access. Claude Code skills have full network access. Claude.ai skills get varying network access depending on admin settings. The docs note: "Custom Skills do not sync across surfaces. Skills uploaded to one surface are not automatically available on others."

For this guide, we are talking about Claude Code skills: filesystem-based, live on your machine, triggered inside your terminal.

## Anatomy of a Skill

Every skill is a directory. `SKILL.md` is the entrypoint. Everything else is optional.

Here is the directory layout Anthropic shows in the Claude Code docs:

```
my-skill/
 SKILL.md           # Main instructions (required)
 template.md        # Template for Claude to fill in
 examples/
    sample.md      # Example output showing expected format
 scripts/
     validate.sh    # Script Claude can execute
```

`SKILL.md` has two parts: YAML frontmatter between `---` markers, and markdown content after. The frontmatter tells Claude when to use the skill. The markdown is what Claude reads and follows once the skill is invoked.

Here is a real, working skill, lightly sanitized. This is a `/clean` skill that reclaims disk space by removing `node_modules`, build caches, and package manager junk:

```markdown
---
description: Reclaim disk space by nuking node_modules, .next caches, and package manager caches. Safe, everything reinstalls on demand.
---

# /clean  Disk Space Reclaimer

Run these steps in order:

## 1. Show current disk usage
`!`df -h / | tail -1``

## 2. Scan for reclaimable space (run in parallel)
`!`find ~/Developer -name "node_modules" -type d -maxdepth 4 -prune 2>/dev/null | while read d; do du -s "$d" 2>/dev/null; done | awk '{s+=$1} END {printf "node_modules: %.1f GB\n", s/1048576}'``

## 3. Show the user a summary table and total, then ask for confirmation

## 4. On confirmation, run cleanup (parallel where possible)
`!`find ~/Developer -name "node_modules" -type d -prune -exec rm -rf {} + 2>/dev/null``

## 5. Show final disk usage
`!`df -h / | tail -1``

Report before/after free space.

## Notes
- Everything deleted is regenerated by `npm install` or `next dev`
- Do NOT delete `.env`, `.env.local`, or any config files
```

Three things to notice. First, the description is short and action-oriented. Second, there are real numbered steps, not vague guidance. Third, the `` !`command` `` syntax runs shell commands **before** Claude sees the prompt, so the output is injected as real data, not as a task for Claude to do itself. The docs call this **dynamic context injection** and note that it is preprocessing, not something Claude executes.

## The Frontmatter Schema

The Claude Code docs list every frontmatter field. I am quoting them directly because the schema matters and guessing at it is how skills mysteriously fail to load.

All fields are optional. Only `description` is recommended.

- `name` (no). Display name. Defaults to the directory name. Lowercase letters, numbers, hyphens only, max 64 characters.
- `description` (recommended). What the skill does and when to use it. Claude uses this to decide when to apply the skill. Combined with `when_to_use`, it is truncated at 1,536 characters in the listing.
- `when_to_use` (no). Additional trigger context. Appended to description in the listing.
- `argument-hint` (no). Shown during autocomplete. Example: `[issue-number]`.
- `disable-model-invocation` (no). Set `true` to prevent Claude from auto-loading. Default `false`.
- `user-invocable` (no). Set `false` to hide from the `/` menu. Default `true`.
- `allowed-tools` (no). Tools Claude can use without asking permission. Space-separated string or YAML list.
- `model` (no). Model to use when the skill is active.
- `effort` (no). Effort level. Options: `low`, `medium`, `high`, `xhigh`, `max`.
- `context` (no). Set to `fork` to run in a forked subagent context.
- `agent` (no). Which subagent type to use when `context: fork` is set.
- `hooks` (no). Hooks scoped to this skill's lifecycle.
- `paths` (no). Glob patterns that limit when the skill is activated automatically.
- `shell` (no). `bash` (default) or `powershell`.

For Agent Skills via the Anthropic API, the rules on `name` and `description` tighten: max 64 characters for `name`, max 1024 characters for `description`, and the `name` cannot contain the reserved words "anthropic" or "claude". These come from the Agent Skills overview.

## Where Skills Live

Where you put a skill determines who can use it. From the Claude Code docs:

| Location | Path | Applies to |
| --- | --- | --- |
| Enterprise | Managed settings | All users in your organization |
| Personal | `~/.claude/skills//SKILL.md` | All your projects |
| Project | `.claude/skills//SKILL.md` | This project only |
| Plugin | `/skills//SKILL.md` | Where plugin is enabled |

When skill names collide across levels, the docs specify the order: "enterprise > personal > project". Plugin skills are namespaced as `plugin-name:skill-name` so they cannot conflict.

Two important details often missed. First, the old `.claude/commands/` directory still works. Per the docs: "Custom commands have been merged into skills. A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way." If a skill and a command share a name, the skill wins.

Second, Claude Code watches these directories for changes. Adding or editing a skill "takes effect within the current session without restarting." The exception: creating a top-level skills directory that did not exist when the session started requires restarting Claude Code.

## How Claude Decides Which Skill to Invoke

This is the part that trips up every first-time skill author.

Claude does not grep your message for keywords. Claude reads the full list of skill names and descriptions as part of its system prompt, then uses normal reasoning to pick one. The docs are blunt about why that matters: "Check the description includes keywords users would naturally say."

So your description is not metadata for humans. It is a prompt for Claude. Write it the way you would brief a new hire on when to use a specific runbook. Something like "Deploy the application to production. Use when the user says 'ship it', 'deploy', or 'go live' on the current branch" tells Claude two things: what the skill does, and the phrases that should trigger it.

The docs also flag the sharp edge: "Skill descriptions are loaded into context so Claude knows what's available. All skill names are always included, but if you have many skills, descriptions are shortened to fit the character budget." The budget is 1% of the context window with a fallback of 8,000 characters. You can raise it with the `SLASH_COMMAND_TOOL_CHAR_BUDGET` environment variable, but the cleaner fix is to front-load the use case in the first 1,536 characters.

There are three ways to control invocation. Default: both you and Claude can invoke. `disable-model-invocation: true`: only you can invoke, via `/skill-name`. `user-invocable: false`: only Claude can invoke, which is useful for background context that is not a meaningful command.

## Writing Your First Skill

The Claude Code docs walk through building an `explain-code` skill. Here is the minimum viable version for your own workflow.

Step one: create the directory.

```bash
mkdir -p ~/.claude/skills/explain-code
```

Step two: write `~/.claude/skills/explain-code/SKILL.md`.

```markdown
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works, teaching about a codebase, or when the user asks "how does this work?"
---

When explaining code, always include:

1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow, structure, or relationships
3. **Walk through the code**: Explain step-by-step what happens
4. **Highlight a gotcha**: What's a common mistake or misconception?

Keep explanations conversational. For complex concepts, use multiple analogies.
```

Step three: test it. In Claude Code, ask "How does this code work?" on any file and Claude should load the skill automatically. Or invoke it directly with `/explain-code src/auth/login.ts`.

That is the whole loop. Write once. Reuse forever. Share by committing the file.

## Skills vs CLAUDE.md vs Hooks vs MCPs

All four extend Claude Code. They solve different problems.

**CLAUDE.md** is always in context. It is the right place for facts about your project: stack, conventions, where things live, what not to touch. If you find yourself writing a procedure in `CLAUDE.md`, move it to a skill. The docs are explicit about this tradeoff.

**Skills** are procedural knowledge loaded on demand. Checklists, runbooks, multi-step tasks. Their body only enters context when invoked.

**Hooks** are deterministic. They run on harness events like `PostToolUse` or `Stop`, executing shell commands without asking Claude. Hooks are what you use when you want something to happen automatically every time, not when Claude decides. A hook that runs Prettier after every `Edit` is not a skill, it is a hook.

**MCP servers** expose external tools as APIs Claude can call. A GitHub MCP server gives Claude `create_issue` and `list_prs` tools. A Postgres MCP server gives Claude database queries. Skills wrap procedures Claude already knows how to do. MCPs wrap capabilities Claude does not have access to otherwise.

A rough decision tree: procedure that varies in execution, use a skill. Deterministic automation, use a hook. External system access, use an MCP. Permanent project facts, use `CLAUDE.md`.

## Where to Find Good Skills

Three starting points.

**Anthropic's public repository** at `github.com/anthropics/skills` ships official skills including document processing, the Claude API skill, and others. This is the reference implementation.

**The Agent Skills ecosystem** lives at `agentskills.io`. The standard is supported by roughly thirty agent products, so skills written for one often work in others with no changes.

**Community marketplaces** package and distribute skills. Plugins on Claude Code can bundle multiple skills plus agents, hooks, and MCP servers. The plugin docs show the structure: a `.claude-plugin/plugin.json` manifest at the root, then a `skills/` directory containing your skill folders. Plugin skills get namespaced as `plugin-name:skill-name` automatically, so you never have to worry about name collisions.

## Skill Builder: Skip the Blank File

Writing your first skill from scratch is annoying. You are guessing at schema, naming conventions, description wording, and whether to use bash injection or plain markdown.

The [Skill Builder](/skills) on Developers Digest generates a valid `SKILL.md` from a short description of what you want the skill to do. Paste in "I want a skill that audits Lighthouse scores for every page in my Next.js app and reports regressions." It returns a complete skill folder structure with frontmatter tuned for auto-invocation, a body that uses real shell injection for the audit run, and a suggested directory path for personal vs project scope.

Use it as a scaffold. Edit the output. Commit it. The first skill is the hardest. After that, you build a library.

## The Shift

The jump from chatting with Claude Code to using Claude Code with a skill library is the same jump as going from a blank terminal to a `.zshrc` with your favorite aliases. You stop doing the same thing twice. You start composing.

Skills are the portable unit. They follow an open standard, load only when needed, and compose with hooks and MCPs. Every repeated instruction you have typed into Claude Code is a skill waiting to be written.

Pick one. Write the frontmatter. Paste the steps. Save the file. Next session, type the trigger phrase and watch your own words come back as infrastructure.

## FAQ

### What is the difference between a Claude Code skill and CLAUDE.md?

CLAUDE.md content is always loaded into context at the start of every session - it is the right place for project facts, conventions, and short rules. A skill's body only loads when invoked, so long procedures cost almost nothing until needed. If something in CLAUDE.md has grown into a multi-step checklist or runbook, move it to a skill.

### How many skills can I install before performance suffers?

You can have dozens of skills installed with minimal cost. Claude reads only the name and description of each skill (roughly 100 tokens each) until one is invoked. The skill body loads on demand, so fifty skills cost the same as five in steady state.

### Where should I put my skills - personal or project?

Put skills in `~/.claude/skills/` for personal workflows you use across all projects (like disk cleanup, git shortcuts, or deployment scripts). Put skills in `.claude/skills/` at the project root for team-shared workflows that belong in version control (like project-specific linting, release checklists, or codebase-aware audits).

### How does Claude decide when to load a skill automatically?

Claude reads all skill descriptions as part of its system prompt, then uses normal reasoning to decide if one applies. Your description is a prompt for Claude, not metadata for humans. Front-load keywords users would naturally say: "Deploy the application. Use when the user says 'ship it', 'deploy', or 'go live'."

### Can I use Claude Code skills in other AI tools like Cursor or Codex?

Yes. Claude Code skills follow the Agent Skills open standard at agentskills.io. The same `SKILL.md` format works in Cursor, Codex, Gemini CLI, OpenCode, Goose, and roughly thirty other tools. Write once, use everywhere - though runtime features like network access vary by host.

### What is the `` !`command` `` syntax inside skills?

It is dynamic context injection - the command runs before Claude sees the prompt, and the output is injected as real data. This is preprocessing, not something Claude executes. Use it to gather system state, run audits, or fetch data that the skill's instructions will reference.

### How do I prevent a skill from running automatically?

Add `disable-model-invocation: true` to the frontmatter. The skill will only run when you invoke it directly with `/skill-name`. Useful for destructive operations like cleanup scripts or deployments where you want explicit control.

### Do skills work with the Claude API and Claude.ai, or only Claude Code?

All three surfaces support skills, but they are separate runtimes. API skills run in Anthropic's code execution container with no network access. Claude.ai skills get admin-controlled network access. Claude Code skills have full network access on your machine. Skills do not sync across surfaces automatically - you manage each independently.

## References

- [Extend Claude with skills (Claude Code docs)](https://code.claude.com/docs/en/skills)
- [Create plugins (Claude Code docs)](https://code.claude.com/docs/en/plugins)
- [Agent Skills overview (Claude API docs)](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
- [Agent Skills open standard (agentskills.io)](https://agentskills.io/home)
- [Equipping agents for the real world with Agent Skills (Anthropic engineering)](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills)
- [anthropics/skills repository (GitHub)](https://github.com/anthropics/skills)
- [What are Skills? (Claude Help Center)](https://support.claude.com/en/articles/12512176-what-are-skills)


What Is an AI Coding Agent? The Complete 2026 Guide
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
Four years ago GitHub Copilot finished your line of code. Today a tool called Devin opens pull requests while you sleep, and GitHub itself ships a cloud agent you can assign issues to like a coworker. Something changed between those two sentences, and the word for that change is `agent`. The buying question lives one layer up in the [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026), but the mechanics start here.

Most writing about AI coding agents either oversells them as autonomous developers or dismisses them as fancy autocomplete. Neither is useful. This guide does the boring thing instead: it defines what a coding agent actually is in 2026, maps the categories, names the leaders with links to their own docs, and tells you what they still cannot do. Every capability claim points to a primary source. For the developer-tool buying view, keep the [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) open next to this guide.

## Navigation Map

Use this as the beginner entry point, then branch by intent:

| If you want... | Read next |
|----------------|-----------|
| Tool selection | [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) |
| Pricing and limits | [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) |
| The core agent shoot-out | [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) |
| Claude Code fundamentals | [What is Claude Code](/blog/what-is-claude-code-complete-guide-2026) |
| Cursor fundamentals | [What is Cursor AI code editor](/blog/what-is-cursor-ai-code-editor-2026) |
| MCP and external tools | [Complete MCP server guide](/blog/complete-guide-mcp-servers) |

For vendor attribution, the most important primary sources are the [Claude Code overview](https://code.claude.com/docs/en/overview), [OpenAI Codex repo](https://github.com/openai/codex), [Cursor docs](https://cursor.com/docs), and [GitHub Copilot coding-agent docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent).

## The 30-Second Definition

An AI coding agent is a program that takes a task in natural language, decides which actions to take, uses tools like file editors, shells, and browsers to carry them out, and keeps going across multiple steps until the task is done or it hits a limit.

The word that does the work is `tools`. Copilot suggested text. An agent suggests, then runs the tests, reads the output, edits the file again, runs the tests again, and opens a pull request. Anthropic's own description of Claude Code puts it this way: "Claude Code is an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools" ([docs](https://code.claude.com/docs/en/overview)). That tool loop is the same primitive behind [how to build AI agents in TypeScript](/blog/how-to-build-ai-agents-typescript).

That sentence captures the three moves: read, edit, run. Stitch those together in a loop with a language model deciding what to do next, and you have an agent.

## The Taxonomy: Five Kinds of Agent

Not every agent does the same job. It helps to split the category into five shapes.

**1. Terminal agents.** Interactive CLIs that sit in your shell and drive your machine. Claude Code, OpenAI's Codex CLI, Aider, Factory's CLI droids. These are REPL-style tools you run in a repo and talk to. Codex CLI's GitHub repo tagline is "Lightweight coding agent that runs in your terminal" ([github.com/openai/codex](https://github.com/openai/codex)).

**2. IDE agents.** Embedded in your editor. Cursor Agent lives inside Cursor. The Claude Code VS Code extension adds inline diffs, plan review, and chat in the editor ([docs](https://code.claude.com/docs/en/overview)). GitHub Copilot's agent mode runs inside VS Code and JetBrains. These agents see the file you have open and the selection you made.

**3. Cloud/background agents.** Spawn a sandboxed VM, hand it a task, close the tab, come back to a pull request. Cursor's cloud agents (formerly background agents) "leverage the same agent fundamentals but run in isolated environments in the cloud instead of on your local machine" ([Cursor docs](https://cursor.com/docs/background-agent)). GitHub Copilot's cloud agent "can work independently in the background to complete tasks, just like a human developer" ([GitHub docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)). Devin, Factory Droids, and Replit Agent all belong in this bucket too.

**4. App builders.** Agents that build a deployable app from a prompt, not a patch. Replit Agent 4 promotes "Parallel Task Execution" and "Multi-Format Building" for "web apps, mobile apps, landing pages, decks, and videos within a single project" ([Replit](https://replit.com/agent)). v0 sits here too. You type what you want, the agent ships a URL.

**5. Managed agent platforms.** The newest category. Infrastructure for running your own agents as a service. Anthropic launched Claude Managed Agents on April 8, 2026 with "sandboxed code execution, checkpointing, credential management, scoped permissions, and end-to-end tracing" ([claude.com/blog/claude-managed-agents](https://claude.com/blog/claude-managed-agents)). OpenAI's Agents SDK and the platform layer underneath it play the same role for OpenAI's stack, which is why the [OpenAI Codex and managed agents](/blog/openai-codex-managed-agents-aws-2026) piece is the natural follow-up.

Most tools in 2026 blur these lines. Claude Code ships in terminal, VS Code, JetBrains, Desktop, Web, and iOS ([docs](https://code.claude.com/docs/en/overview)). Factory Droids describe themselves as "The only software development agents that work everywhere you do" across IDE, terminal, desktop, web, CLI, and Slack ([factory.ai](https://factory.ai/)).

## How an Agent Works Under the Hood

An agent is three things stitched together: a model, a set of tools, and a loop.

The model is the brain. Usually a frontier model like Claude Opus 4.7, GPT-5.4, or [Gemini](/blog/gemini-deep-research) 3. The tools are the hands. Read, Write, Edit, Bash, Grep, WebSearch, and anything else you expose. The loop is what makes it agentic: the model picks a tool, runs it, reads the result, decides what to do next, and repeats.

Claude Code's public documentation lists the kinds of work the loop handles: "writing tests for untested code, fixing lint errors across a project, resolving merge conflicts, updating dependencies, and writing release notes" ([docs](https://code.claude.com/docs/en/overview)). None of those are single-shot completions. They are multi-step procedures that only work because the agent can read, act, check, and react.

Two extensions matter in 2026. They are also where the internal-link map branches: MCP belongs with the [MCP beginner guide](/blog/what-is-an-mcp-server-beginner-guide-2026), while sandboxed execution belongs with the [Codex cloud security playbook](/blog/openai-codex-cloud-security-playbook-2026).

**MCP (Model Context Protocol).** An open standard for connecting agents to external data and tools. Postgres, GitHub, Linear, Figma, Playwright, whatever you have. Claude Code treats MCP as a first-class primitive: "With MCP, Claude Code can read your design docs in Google Drive, update tickets in Jira, pull data from Slack, or use your own custom tooling" ([docs](https://code.claude.com/docs/en/overview)). Cursor's cloud agents support MCP servers for "access to external tools and data sources like databases, APIs, and third-party services" ([docs](https://cursor.com/docs/background-agent)). The [complete MCP server guide](/blog/complete-guide-mcp-servers) goes deeper on how that protocol actually works.

**Sandboxed execution.** Running an agent on your laptop is fine for solo work. Running it for a team means isolating every task in a fresh environment so a stuck loop cannot rm-rf your home directory. GitHub Copilot's cloud agent runs "in its own ephemeral development environment, powered by GitHub Actions" ([docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)). Claude Managed Agents ship this as infrastructure you rent by the session-hour ([claude.com](https://claude.com/blog/claude-managed-agents)).

## What Agents Can Actually Do in 2026

Pull this from the docs, not from hype.

Claude Code can "plan the approach, write the code across multiple files, and verify it works" and for bugs "traces the issue through your codebase, identifies the root cause, and implements a fix" ([docs](https://code.claude.com/docs/en/overview)). It stages changes, writes commit messages, creates branches, and opens pull requests. It runs on a schedule via Routines on Anthropic infrastructure so "they keep running even when your computer is off" ([docs](https://code.claude.com/docs/en/overview)).

GitHub Copilot's cloud agent "excels at low-to-medium complexity tasks in well-tested codebases, from adding features and fixing bugs to extending tests, refactoring code, and improving documentation" ([docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)). You assign a GitHub issue to it, and it opens a PR on a branch.

Cursor's cloud agents can "build, test, and interact with the changed software" and use desktop and browser control for UI-verifying changes ([docs](https://cursor.com/docs/background-agent)).

Aider describes itself as a tool that "lets you pair program with LLMs to start a new project or build on your existing codebase" with automatic git integration and a map of your whole codebase for context ([aider.chat](https://aider.chat/)).

Factory Droids handle "complete tasks like refactors, incident response, and migrations" across IDE, terminal, desktop, web, CLI, and chat ([factory.ai](https://factory.ai/)).

Replit Agent 4 runs "independent tasks simultaneously" and covers "auth, database, back-end functionality and front-end design all at once" ([replit.com/agent](https://replit.com/agent)).

That is the honest list. Writing code across files, fixing bugs, extending tests, handling migrations, running on a schedule, opening pull requests, deploying apps.

## The Top Agents Compared

Every claim below points to the vendor's own page. Pricing and capability both.

### Claude Code (Anthropic)

The multi-surface agent platform. Terminal, VS Code, JetBrains, Desktop app, Web, iOS, Slack, Chrome ([docs](https://code.claude.com/docs/en/overview)). Install with `curl -fsSL https://claude.ai/install.sh | bash` on macOS or Linux. Extensible through Skills, Subagents, Hooks, and MCP servers. Runs scheduled Routines on Anthropic infrastructure.

Pricing: included with Claude subscriptions (see [claude.com/pricing](https://claude.com/pricing)).

### Cursor Agent and Cloud Agents

Inside the Cursor editor. Cloud Agents run in isolated cloud environments, can control desktop and browser, and can be launched from Web, Desktop, Slack, GitHub, Linear, and API ([docs](https://cursor.com/docs/background-agent)). Cloud agents bill at "API pricing for the selected model" with user-defined spend limits ([docs](https://cursor.com/docs/background-agent)).

### OpenAI Codex CLI

Open-source coding agent installed with `npm install -g @openai/codex` or `brew install --cask codex`. Integrates with ChatGPT plans (Plus, Pro, Business, Edu, Enterprise) when you sign in with your ChatGPT account ([github.com/openai/codex](https://github.com/openai/codex)). Built in Rust. Ships a GitHub Action at [openai/codex-action](https://github.com/openai/codex-action) for CI.

### GitHub Copilot Coding Agent (Cloud Agent)

Assign a GitHub issue to `@copilot`, get a PR on a branch. Runs in an ephemeral GitHub Actions environment ([docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)).

Plans per [GitHub's pricing page](https://github.com/features/copilot/plans):

- Free: $0/month, 50 agent/chat requests monthly, 2,000 completions, Haiku 4.5 and GPT-5 mini
- Pro: $10/user/month, unlimited agent mode with GPT-5 mini, 300 premium requests, cloud agent access
- Pro+: $39/user/month, 1,500 premium requests, Claude Opus 4.6 and all available models, delegation to third-party coding agents, GitHub Spark
- Business and Enterprise: contact sales

### Cognition Devin

The original "autonomous software engineer" framing. Plans 2026 per [devin.ai/pricing](https://devin.ai/pricing):

- Free: Devin Review and DeepWiki access
- Pro: $20/month with pay-as-you-go overages, Slack, Linear, [MCP](/blog/what-is-mcp) integrations
- Max: $200/month with increased Devin and [Windsurf](/blog/windsurf-vs-cursor) IDE quotas
- Teams: $80/month per seat with unlimited team members and shared collaboration
- Enterprise: custom pricing

### Factory Droids

Multi-surface coding agents with five interfaces. Per [factory.ai/pricing](https://factory.ai/pricing):

- Pro: $20/month, desktop, web, CLI access, up to 2 team members
- Max: $200/month, 10x usage, up to 5 seats
- Enterprise: custom, unlimited seats, SSO, on-premise options

### Aider

Open source terminal pair programmer. Works with Claude, DeepSeek, OpenAI, and "almost any LLM, including local models" ([aider.chat](https://aider.chat/)). 42K GitHub stars and 88% of recent code written by Aider itself, per the project.

Pricing: free. You pay the model provider.

### Replit Agent

Cloud-first app builder. Per [replit.com/pricing](https://replit.com/pricing):

- Starter: free, daily Agent credits, publish 1 app
- Replit Core: $20/month annual ($25 monthly), $25 in monthly credits, autonomous long builds
- Replit Pro: $95/month annual ($100 monthly), $100 in monthly credits, private deployments, 28-day database restore
- Enterprise: custom

### Claude Managed Agents (Anthropic)

Infrastructure layer for running agents as a service. Launched April 8, 2026. Includes "sandboxed code execution, checkpointing, credential management, scoped permissions, and end-to-end tracing" ([claude.com/blog/claude-managed-agents](https://claude.com/blog/claude-managed-agents)). Costs "$0.08 per session hour in addition to the standard API Claude token prices." Public beta on the Claude Platform with Notion, Rakuten, and Asana as early adopters.

### Cognition Devin, Cursor, Copilot, Factory, Replit, Claude Code side by side

| Agent | Best for | Where it runs | Billing model |
|---|---|---|---|
| Claude Code | Multi-surface agent work, skills, plugins | Terminal, IDE, Desktop, Web, Cloud | Claude subscription |
| Cursor Agent + Cloud | IDE-native and parallel cloud tasks | Editor + isolated cloud VMs | API pricing per model |
| Copilot Cloud Agent | Issue-to-PR in GitHub-native teams | GitHub Actions ephemeral env | Per-seat + premium requests |
| Devin | Long-horizon autonomous coding | Devin cloud | Per-seat, pay-as-you-go overages |
| Factory Droids | Multi-surface with token transparency | IDE, CLI, Slack, Web, Desktop | Per-seat, token-based |
| Replit Agent | App building, zero to deployed | Replit cloud | Credits, seat-based |
| Aider | Local terminal pair programming, BYOM | Your terminal | Free + model costs |
| OpenAI Codex CLI | Terminal agent, ChatGPT-integrated | Your terminal | ChatGPT plan |
| Claude Managed Agents | Running agents as a service | Anthropic infra | Per session-hour + tokens |

## What Agents Are Bad At (Honest Version)

Docs will not tell you this. Experience will.

**Visual and spatial changes.** "Move the button, resize the card, align the grid" still trips most agents. They can read the CSS and guess, but they cannot see the result without computer-use tooling, and even then their eyes are bad.

**Cost predictability.** A stuck agent burns tokens in a loop. Managed session-hour pricing (Anthropic's $0.08/hr + tokens, per [claude.com](https://claude.com/blog/claude-managed-agents)) helps but does not cap the token side. GitHub sells premium requests in buckets of 300 (Pro) or 1,500 (Pro+) with overflow billed by usage ([plans](https://github.com/features/copilot/plans)).

**Large refactors that span shared state.** An agent can rename a function in 40 files. It struggles when the rename implies a data-model change that ripples through types, migrations, and tests unevenly.

**Model and tool picking.** Most platforms expose five or six models. Picking the right one for the task is on you.

**Review quality.** GitHub's own docs call out that the cloud agent "excels at low-to-medium complexity tasks in well-tested codebases" ([docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)). Read that as: give it narrow, testable work. Architecture still belongs to a human.

## Getting Started in 10 Minutes

Pick one and try a real task. Do not read another comparison article.

**If you want the fastest local install:** Claude Code.

```bash
curl -fsSL https://claude.ai/install.sh | bash
cd your-project
claude
```

Then ask it to write tests for one module and run them. Full install flow at [code.claude.com](https://code.claude.com/docs/en/overview).

**If you want an open-source option with BYO model:** [Aider](/blog/aider-vs-claude-code-2026-update).

Install from [aider.chat](https://aider.chat/) and run it in a repo with your Anthropic or OpenAI key. Works with local models too.

**If you want the ChatGPT-integrated terminal agent:** OpenAI Codex CLI.

```bash
npm install -g @openai/codex
codex
```

Sign in with your ChatGPT account per the [repo README](https://github.com/openai/codex).

**If you are already on GitHub and want issue-to-PR:** assign a GitHub issue to Copilot. Requires Pro, Pro+, Business, or Enterprise ([docs](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)).

**If you want a cloud VM to run long tasks:** Cursor Cloud Agents or Devin. Cursor's are launched from Web, Desktop, Slack, GitHub, Linear, or API ([docs](https://cursor.com/docs/background-agent)).

Run one task. Watch what happens. Adjust.

## The Honest Takeaway

An AI coding agent is a language model with tools and a loop. In 2026 it will write tests, open pull requests, trace bugs, and deploy web apps. It will not replace the engineer reading the diff. Pick the surface that matches where you already work. Start with narrow tasks. Measure what it costs you on real work, not on demo videos.

The frontier is moving faster than any blog post. Check the docs linked below before quoting any number from this one, and use the [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026) when the question shifts from capability to budget.

## Frequently Asked Questions

### What is the difference between GitHub Copilot and an AI coding agent?

GitHub Copilot's autocomplete suggests code inline as you type - single-line or small-block completions. An AI coding agent like Claude Code, Cursor Agent, or GitHub Copilot's own cloud agent takes a task description, then runs a multi-step loop: reading files, editing code, running tests, checking results, and iterating until the task is done. The agent uses tools (shell, file system, browser) while autocomplete only suggests text. GitHub now offers both: Copilot completions for inline suggestions, and Copilot cloud agent for issue-to-PR workflows.

### Are AI coding agents replacing developers?

No. Agents excel at well-scoped, testable tasks like writing tests, fixing lint errors, handling migrations, and updating dependencies. GitHub's own documentation describes its cloud agent as handling "low-to-medium complexity tasks in well-tested codebases." Architecture decisions, debugging novel issues, understanding business context, and reviewing agent output still require human judgment. Agents multiply developer output on routine work but do not replace the developer reading the diff.

### How much do AI coding agents cost?

Pricing varies by vendor. Claude Code is included with Claude subscriptions. Cursor Agent uses API pricing per model with user-defined spend limits. GitHub Copilot Pro costs $10/month with cloud agent access. Devin Pro is $20/month with pay-as-you-go overages. Aider is free - you pay the model provider directly. Claude Managed Agents charge $0.08 per session-hour plus standard API token costs. The [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026) has current numbers for all major tools.

### Can AI coding agents work with my existing codebase?

Yes. Terminal agents like Claude Code, Codex CLI, and Aider run directly in your repo. IDE agents like Cursor Agent and the Claude Code VS Code extension work with whatever project you have open. Cloud agents clone your repo into a sandboxed environment. All modern agents support git, can read your entire codebase for context, and write changes across multiple files. MCP (Model Context Protocol) extends agent reach to external tools like databases, issue trackers, and design files.

### What is the best AI coding agent in 2026?

It depends on where you work. Claude Code covers the most surfaces - terminal, VS Code, JetBrains, Desktop, Web, iOS, Slack. Cursor Agent is best if you already use Cursor as your editor. GitHub Copilot cloud agent fits teams that want issue-to-PR automation within GitHub. Aider is the best open-source option with bring-your-own-model support. Devin and Factory Droids handle longer-horizon autonomous work. The [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026) breaks down capabilities by use case.

### How do AI coding agents actually work?

An agent is three components: a model (the brain), tools (the hands), and a loop. The model - usually a frontier model like Claude Opus 4.7 or GPT-5.4 - receives a task. It picks a tool (read file, edit code, run shell command), executes it, reads the result, decides what to do next, and repeats until the task is done or a limit is reached. MCP (Model Context Protocol) lets agents connect to external data sources and services. Sandboxed execution isolates agent work so a stuck loop cannot damage your system.

### Can AI coding agents run without supervision?

Yes, with limits. Cloud agents from Cursor, GitHub, and Devin run in isolated environments while you close the tab. Claude Code Routines run on a schedule on Anthropic infrastructure. But "without supervision" does not mean "without review." Agents still produce pull requests that need human review. The safer pattern is narrow, testable tasks with clear success criteria, not open-ended autonomous coding. GitHub's cloud agent documentation explicitly recommends well-tested codebases with good CI coverage.

### What tasks are AI coding agents bad at?

Visual and spatial UI changes - moving buttons, aligning grids, resizing cards - still trip most agents because they cannot see the rendered result. Large refactors that span shared state are risky when changes ripple unevenly through types, migrations, and tests. Cost predictability is weak when a stuck agent burns tokens in a loop. Architecture decisions and novel debugging require human judgment. Use agents for narrow, testable work and review everything they produce.

## References

- Claude Code overview: [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview)
- Claude pricing: [claude.com/pricing](https://claude.com/pricing)
- Claude Managed Agents launch post: [claude.com/blog/claude-managed-agents](https://claude.com/blog/claude-managed-agents)
- OpenAI Codex CLI repo: [github.com/openai/codex](https://github.com/openai/codex)
- OpenAI Codex GitHub Action: [github.com/openai/codex-action](https://github.com/openai/codex-action)
- Cursor docs: [cursor.com/docs](https://cursor.com/docs)
- Cursor Cloud Agents (formerly Background Agents): [cursor.com/docs/background-agent](https://cursor.com/docs/background-agent)
- GitHub Copilot cloud agent concepts: [docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent](https://docs.github.com/copilot/concepts/agents/coding-agent/about-coding-agent)
- GitHub Copilot plans: [github.com/features/copilot/plans](https://github.com/features/copilot/plans)
- Devin pricing: [devin.ai/pricing](https://devin.ai/pricing)
- Factory pricing: [factory.ai/pricing](https://factory.ai/pricing)
- Factory home: [factory.ai](https://factory.ai/)
- Replit Agent: [replit.com/agent](https://replit.com/agent)
- Replit pricing: [replit.com/pricing](https://replit.com/pricing)
- Aider: [aider.chat](https://aider.chat/)


What Is an MCP Server? A Developer's Beginner Guide (2026)
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
## The acronym you cannot avoid

If you have touched an [AI coding tool](/blog/ai-coding-tools-comparison-matrix-2026) in the last twelve months, you have seen the letters MCP. They show up in Claude Code docs, in the Cursor settings panel, in every new Anthropic launch video, and now in the OpenAI Codex docs too. In April 2026 the MCP Directory we maintain at mcp.developersdigest.tech lists 271 active servers. The official Anthropic MCP registry tracks thousands more.

Most beginner posts either wave their hands ("it connects AI to tools") or drown you in JSON-RPC frame diagrams. This guide sits in between. Everything you are about to read is pulled directly from the official spec at modelcontextprotocol.io and the [Claude Code](/blog/what-is-claude-code-complete-guide-2026) MCP documentation. If a claim is not sourced to a primary doc, it is not in this post.

## What MCP actually is, in the spec's own words

The [Model Context Protocol](/blog/what-is-mcp) is described on the official introduction page as "an open-source standard for connecting AI applications to external systems." The same page uses the now-famous analogy: "Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems."

That is the whole idea. Before MCP, every AI tool that wanted to talk to your filesystem, your database, or your Slack had to ship a bespoke integration. [Anthropic](/blog/anthropic-vs-openai-developer-experience) open-sourced MCP in November 2024 to replace that N-by-M mess with a single protocol. One server, every client.

The Wikipedia entry on MCP and coverage in The New Stack both note that the approach worked. OpenAI formally adopted the protocol in March 2025, and the OpenAI Codex docs at `developers.openai.com/codex/mcp` now list first-party MCP support. Microsoft Copilot Studio, Google's Gemini CLI, Cursor, VS Code, and Claude Code all ship MCP clients today. In December 2025 Anthropic donated the protocol to the Agentic AI Foundation under the Linux Foundation, with Block and OpenAI as co-founders.

That is what "won" looks like for a protocol: your competitor ships it.

## The architecture: hosts, clients, servers

MCP defines three roles.

A **host** is the AI application you sit in front of. Claude Code, Cursor, ChatGPT Desktop, Gemini CLI. The host runs the LLM and owns the conversation.

A **client** is the connection the host opens for each server. One client per server, one-to-one.

A **server** is a small program that exposes capabilities over the protocol. It runs locally as a subprocess or remotely as an HTTP service. It does not care which host is on the other end.

The transport between client and server is JSON-RPC 2.0 encoded as UTF-8. That is fixed by the spec.

## The three primitives

Every MCP server exposes some combination of three primitives. This is the part that trips up beginners the most, because they look similar but have different ownership semantics.

### Tools

From the spec: "Tools in MCP are designed to be model-controlled, meaning that the language model can discover and invoke tools automatically based on its contextual understanding and the user's prompts."

Tools are functions the model can call. The server declares them by listing a `name`, `description`, and `inputSchema` (JSON Schema). When the client asks, the server returns the list. When the model wants to invoke one, it sends `tools/call` with arguments, and the server returns a result.

A tool definition from the spec looks like this:

```json
{
  "name": "get_weather",
  "title": "Weather Information Provider",
  "description": "Get current weather information for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or zip code" }
    },
    "required": ["location"]
  }
}
```

The spec is explicit that "there SHOULD always be a human in the loop with the ability to deny tool invocations." That is why Claude Code prompts you before running a new tool the first time.

### Resources

Resources are "application-driven" context: files, database rows, API payloads, anything the host might want to feed into the model. Each resource is identified by a URI. The spec defines standard schemes like `file://`, `https://`, and `git://`, and allows custom ones.

Clients call `resources/list` to discover what is available, then `resources/read` with a URI to fetch contents. Resources can also be subscribable. The server notifies the client when a file changes.

The key distinction: the **host** decides when to pull in a resource, not the model. In Cursor, the `@` picker that lets you attach a file to a prompt is a resource picker. Tools are for the model to invoke; resources are for the app (or the user) to attach.

### Prompts

Prompts are "user-controlled" templates. The spec describes them as "structured messages and instructions for interacting with language models," and the docs show the canonical UI: slash commands.

A prompt template is a named, argument-accepting message builder. The server returns a list of message objects when asked. Most MCP clients surface these as slash commands like `/review-code` or `/summarize-thread`.

The mental model: tools are the model's hands, resources are its eyes, prompts are its phrasebook.

## Transports: stdio and streamable HTTP

There are two transports in the current spec, and exactly one of them is new enough that most beginner posts get it wrong.

The spec is direct: "The protocol currently defines two standard transport mechanisms for client-server communication: stdio and Streamable HTTP."

### stdio

The client launches the server as a subprocess. JSON-RPC messages flow over `stdin` and `stdout`, delimited by newlines. Logs go to `stderr`. This is the local, on-your-machine transport.

### Streamable HTTP

Introduced in protocol version `2025-03-26`, Streamable HTTP is now the standard remote transport. It uses a single HTTP endpoint that accepts both POST (client-to-server messages) and GET (open an SSE stream for server-to-client messages). It supports resumable sessions via an `Mcp-Session-Id` header.

The older HTTP+SSE transport from protocol version `2024-11-05` is deprecated. The transports spec page includes this note verbatim: "This replaces the HTTP+SSE transport from protocol version 2024-11-05." If an article tells you to "set up an SSE server," it is at least a year out of date. The Claude Code docs also flag this directly: "The SSE (Server-Sent Events) transport is deprecated. Use HTTP servers instead, where available."

Custom transports are allowed. The spec only requires that they preserve JSON-RPC semantics and lifecycle.

## The clients you can actually use today

Rather than hand-wave ecosystem claims, here is what the primary sources show as of April 2026.

- **Claude Code** ships `claude mcp add` as a first-class CLI for managing servers. Docs at `code.claude.com/docs/en/mcp`.
- **Cursor** reads `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project). Docs at `cursor.com/docs/context/mcp`.
- **Claude Desktop** supports MCP via the Developer settings pane.
- **VS Code** ships MCP support in GitHub Copilot Chat per `code.visualstudio.com/docs/copilot/chat/mcp-servers`.
- **OpenAI Codex** supports MCP per `developers.openai.com/codex/mcp`.
- **ChatGPT** exposes MCP servers via Connectors per `developers.openai.com/api/docs/mcp/`.
- **Gemini CLI**, **MCPJam**, **Continue.dev**, and dozens of others are listed on the official clients page at `modelcontextprotocol.io/clients`.

The protocol is client-agnostic by design. Write once, connect anywhere.

## Installing your first MCP server in Claude Code

The Claude Code docs define three scopes for server configuration, and the precise storage location for each.

| Scope | Loads in | Shared | Stored in |
|-------|----------|--------|-----------|
| `local` (default) | Current project only | No | `~/.claude.json` |
| `project` | Current project only | Yes, via version control | `.mcp.json` in project root |
| `user` | All your projects | No | `~/.claude.json` |

Pick one and go. Here are three real installs using real servers from our directory.

### A local stdio server: filesystem

```
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem
```

This gives the model scoped file operations. The server is listed as an official reference implementation on the modelcontextprotocol GitHub org.

### A remote HTTP server: Notion

```
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

Notion publishes an official MCP endpoint. No local install needed. Claude Code handles the OAuth flow on first use.

### A remote HTTP server with a header: custom API

```
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"
```

Per the Claude Code docs, all flags must come before the server name, and the `--` separator precedes the subprocess command for stdio servers.

After any install, type `/mcp` inside Claude Code to see the status of every configured server, their tool counts, and reconnect any that dropped.

## Installing in Cursor

Cursor's docs show the same config shape for every server, just in JSON instead of a CLI.

Create `~/.cursor/mcp.json` for global install or `.cursor/mcp.json` in your project root:

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "env": {}
    },
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}
```

Cursor supports `${env:VARIABLE_NAME}` interpolation inside the config, which is the cleanest way to inject API keys without committing them.

## Picking MCPs that are actually worth it

The MCP Directory at mcp.developersdigest.tech indexes 271 active servers. You do not need 271. You need five. A short list of reference servers from the Anthropic-maintained `modelcontextprotocol/servers` repo, all real and listed in our directory:

- `@modelcontextprotocol/server-filesystem` - sandboxed file operations.
- `@modelcontextprotocol/server-git` - read, search, and diff Git repos.
- `@modelcontextprotocol/server-fetch` - fetch URLs and convert HTML to clean markdown.
- `@modelcontextprotocol/server-postgres` - read-only Postgres queries.
- `@modelcontextprotocol/server-sequential-thinking` - step-by-step reasoning scaffold.

Our full opinionated shortlist lives in [271 MCP Servers Exist. These 5 Actually Make Claude Code Better.](/blog/271-mcp-servers-top-5-that-matter). The filters we apply: actively maintained, one-command install, fills a gap Claude Code does not already cover, returns clean structured output.

## Security: what the spec says, and what to actually do

The spec takes security seriously, and Streamable HTTP has three explicit warnings you should internalize before exposing a server.

From the transports spec: "Servers MUST validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks. When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0). Servers SHOULD implement proper authentication for all connections."

Translation: do not run a public MCP server without auth, do not bind `0.0.0.0` on a dev machine, and validate `Origin`.

On the tools side, the spec requires client-side defences too: "Prompt for user confirmation on sensitive operations. Show tool inputs to the user before calling the server, to avoid malicious or accidental data exfiltration. Validate tool results before passing to LLM."

Practical rules for a beginner:

1. Install servers from publishers you trust. The Anthropic reference servers and the mcp-registry publishers are the safest defaults.
2. Use project scope only for servers the whole team should have. Everything experimental stays in local scope.
3. API keys go in `env` blocks or environment variables, never in committed config.
4. Read the server's README before you let it touch your filesystem. "Sandboxed" servers like `server-filesystem` let you whitelist directories.

## Writing your own MCP server

The fastest path is the official TypeScript SDK.

```
npm init -y
npm install @modelcontextprotocol/sdk zod
```

A minimal server with one tool, built from the shape in the official quickstart:

```ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "hello-mcp", version: "1.0.0" });

server.tool(
  "greet",
  "Return a friendly greeting",
  { name: z.string() },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}.` }],
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);
```

Run it once with `node server.js` to sanity check. Then register it with Claude Code:

```
claude mcp add --transport stdio hello -- node /absolute/path/to/server.js
```

Reload Claude Code, type `/mcp`, and `hello` should show up with one tool. Python, Kotlin, Java, C#, Rust, and Swift SDKs are all listed on `modelcontextprotocol.io` if TypeScript is not your stack.

For deeper dives on building servers, see the official SDK quickstart at `modelcontextprotocol.io/quickstart/server` and the concepts docs linked in the references below.

## What MCP is not

A quick reality check, because misconceptions spread fast.

- MCP is not an agent framework. It does not schedule tasks, plan steps, or orchestrate loops. It is a protocol for exposing capabilities to a model.
- MCP is not a replacement for function calling inside a single LLM provider's SDK. It is the protocol that makes function calling portable across clients.
- MCP does not run the model. The host does. The server just exposes tools, resources, and prompts.
- MCP is not secure by default. The spec defines the mechanics, not the policy. That is on you.

## Next steps

If you are new to MCP, do these four things in order:

1. Install Claude Code or Cursor if you do not have one.
2. Run `claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem` or paste the Cursor config above.
3. Open `/mcp` (Claude) or the MCP panel (Cursor) and confirm the server is connected.
4. Ask your agent to list the contents of a directory. Watch the tool call fire.

That is the entire loop. Everything else - custom servers, remote deployments, prompts, resources - is the same pattern scaled up.

If you want a curated shortlist, read our [271 MCP Servers post](/blog/271-mcp-servers-top-5-that-matter). If you want to browse the full ecosystem, the MCP Directory at mcp.developersdigest.tech is kept current.

USB-C took a decade to win. MCP took about eighteen months. That tells you exactly how starved the AI tooling space was for a standard.

## References

- [modelcontextprotocol.io/introduction](https://modelcontextprotocol.io/introduction) - official definition, USB-C analogy, ecosystem list.
- [modelcontextprotocol.io/docs/concepts/transports](https://modelcontextprotocol.io/docs/concepts/transports) - stdio and Streamable HTTP spec, HTTP+SSE deprecation note.
- [modelcontextprotocol.io/docs/concepts/tools](https://modelcontextprotocol.io/docs/concepts/tools) - tool primitive, schema, safety warnings.
- [modelcontextprotocol.io/docs/concepts/resources](https://modelcontextprotocol.io/docs/concepts/resources) - resources, URI schemes, subscriptions.
- [modelcontextprotocol.io/docs/concepts/prompts](https://modelcontextprotocol.io/docs/concepts/prompts) - prompt templates and user-controlled model.
- [modelcontextprotocol.io/clients](https://modelcontextprotocol.io/clients) - official list of supported clients.
- [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp) - Claude Code install commands, scope storage paths, transport notes.
- [cursor.com/docs/context/mcp](https://cursor.com/docs/context/mcp) - Cursor config file locations and JSON format.
- [developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp) - OpenAI Codex MCP support.
- [developers.openai.com/api/docs/mcp/](https://developers.openai.com/api/docs/mcp/) - ChatGPT MCP connector docs.
- [code.visualstudio.com/docs/copilot/chat/mcp-servers](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) - VS Code MCP support.
- [en.wikipedia.org/wiki/Model_Context_Protocol](https://en.wikipedia.org/wiki/Model_Context_Protocol) - adoption timeline, Linux Foundation donation, OpenAI adoption date.
- [thenewstack.io/why-the-model-context-protocol-won](https://thenewstack.io/why-the-model-context-protocol-won/) - industry context on MCP adoption.
- [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) - official reference servers.
- [mcp.developersdigest.tech](https://mcp.developersdigest.tech) - the MCP Directory, 271 indexed servers as of April 2026.


What Is Claude Code? The Complete Guide for 2026
Sun, 19 Apr 2026 00:00:00 GMT
Claude Code is Anthropic's [AI coding agent](/blog/what-is-an-ai-coding-agent-2026). Per the official docs, it is "an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools. Available in your terminal, IDE, desktop app, and browser." If you have heard the name on engineering Twitter and wondered whether to install it, this is the guide.

This post is for developers who have not used Claude Code before. We will go from zero to a working first session, cover the primitives that actually matter (CLAUDE.md, skills, hooks, MCP, [subagents](/blog/claude-code-sub-agents), plan mode), compare it honestly to the alternatives, and finish with five things to do after you install it. Every feature, command, and pricing number in this post is pulled from Anthropic's official documentation. Sources are listed at the end.

## The 30-second primer

Claude Code is an AI pair programmer that runs across four surfaces: a CLI in your terminal, a VS Code extension, a JetBrains plugin, and a native desktop app for macOS and Windows. There is also a browser version at `claude.ai/code`. All surfaces "connect to the same underlying Claude Code engine, so your CLAUDE.md files, settings, and [MCP servers](/blog/complete-guide-mcp-servers) work across all of them."

For the design side of the same problem, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) with [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

The important distinction: the terminal CLI is not an IDE plugin. It is a long-running agent process. You start it in a project directory with `claude`, describe what you want, and the agent reads, writes, edits, runs tests, and makes commits. Think of it as a teammate that can type into your shell, with the context you give it in a file called `CLAUDE.md`.

## How it actually works

Claude Code runs an agent loop. You send a message, the model decides which tool to call, the harness executes it, and the result feeds back into the model. It keeps going until the task is done or it needs you to answer a question.

At the start of every session, the agent loads memory. [Anthropic](/blog/anthropic-vs-openai-developer-experience)'s docs describe two complementary memory systems:

- **CLAUDE.md files**: markdown you write with persistent instructions (coding standards, architecture, commands).
- **Auto memory**: notes Claude writes itself about things like "build commands, debugging insights, architecture notes, code style preferences, and workflow habits." Auto memory requires Claude Code v2.1.59 or later and lives under `~/.claude/projects//memory/`.

CLAUDE.md files are loaded from a hierarchy: managed policy, project (`./CLAUDE.md` or `./.claude/CLAUDE.md`), user (`~/.claude/CLAUDE.md`), and local (`./CLAUDE.local.md`). The docs recommend keeping each file "under 200 lines" because longer files "consume more context and reduce adherence."

Auto memory loads the first 200 lines or 25KB of `MEMORY.md` into every session. Topic files like `debugging.md` or `patterns.md` are not loaded at startup; Claude reads them on demand.

## Install and first session

Per the official setup page, Claude Code runs on:

- macOS 13.0+
- Windows 10 1809+ or Windows Server 2019+
- Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
- 4 GB+ RAM, x64 or ARM64

The native installer command from the docs:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

For Windows PowerShell:

```powershell
irm https://claude.ai/install.ps1 | iex
```

Homebrew and WinGet are also supported:

```bash
brew install --cask claude-code
```

```powershell
winget install Anthropic.ClaudeCode
```

Native installations "automatically update in the background." Homebrew and WinGet do not.

For a detailed walkthrough of installation, first session, and project configuration, see the [Getting Started with Claude Code](/guides/claude-code-getting-started) guide.

After install, verify with `claude --version`, then go to any project and run `claude`. First launch opens a browser to log in. Anthropic's docs note that Claude Code "requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access." You can also authenticate through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry.

## Core features in 2026

Claude Code in 2026 is not just "a CLI with a chat loop." It has an ecosystem of primitives. Here are the ones documented on `code.claude.com`.

### CLAUDE.md and project memory

The single most important file in any Claude Code project is `CLAUDE.md`. Run `/init` inside a project and Anthropic's docs say Claude "analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers."

CLAUDE.md files can import other files with `@path/to/import` syntax, with a maximum import depth of five hops. For large projects, you can scope rules to specific file paths with `.claude/rules/` files using YAML frontmatter with a `paths` glob. This is the official way to keep project memory organized without bloating context.

### Skills

Skills are the 2026 replacement for custom slash commands. Per the docs: "Custom commands have been merged into skills. A file at `.claude/commands/deploy.md` and a skill at `.claude/skills/deploy/SKILL.md` both create `/deploy` and work the same way."

A skill is a directory with a `SKILL.md` file containing YAML frontmatter and markdown instructions. Frontmatter fields documented in the skills reference include `name`, `description`, `disable-model-invocation`, `user-invocable`, `allowed-tools`, `model`, `effort`, `context`, `agent`, `hooks`, `paths`, and `shell`.

Example from the docs:

```yaml
---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---

When explaining code, always include:

1. **Start with an analogy**
2. **Draw a diagram** using ASCII art
3. **Walk through the code** step-by-step
4. **Highlight a gotcha**
```

Claude Code also ships with bundled skills like `/simplify`, `/batch`, `/debug`, `/loop`, and `/claude-api`. Skills live at four scopes in priority order: enterprise, personal (`~/.claude/skills/`), project (`.claude/skills/`), and plugin.

### Hooks

Hooks are shell commands, HTTP calls, prompts, or subagents that run at specific points in Claude's lifecycle. The docs describe four hook types:

1. **Command hooks** (`type: "command"`) run shell commands
2. **HTTP hooks** (`type: "http"`) POST JSON to a URL
3. **Prompt hooks** (`type: "prompt"`) ask a model for a yes/no decision
4. **Agent hooks** (`type: "agent"`) spawn a subagent to validate

Documented lifecycle events include `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `Notification`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`, `WorktreeCreate`, and more.

A typical use: run Prettier after every file edit, or block destructive `rm -rf` commands before they run. Hooks are configured in `settings.json`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/validate.sh"
          }
        ]
      }
    ]
  }
}
```

### Model Context Protocol (MCP)

MCP is "an open standard for connecting AI tools to external data sources." In Claude Code, you add servers with `claude mcp add`. The docs show three installation scopes:

| Scope   | Loads in             | Shared with team         | Stored in                   |
| ------- | -------------------- | ------------------------ | --------------------------- |
| Local   | Current project only | No                       | `~/.claude.json`            |
| Project | Current project only | Yes, via version control | `.mcp.json` in project root |
| User    | All your projects    | No                       | `~/.claude.json`            |

Add a server with a single command (examples from the docs):

```bash
claude mcp add --transport http stripe https://mcp.stripe.com
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```

Then use `/mcp` inside a Claude Code session to authenticate and manage connections. MCP supports stdio, SSE, HTTP, and WebSocket transports, with OAuth 2.0 for remote servers.

### Subagents

Subagents let a task run in its own isolated context window. Claude Code ships with built-in subagents including **Explore**, **Plan**, and **general-purpose**. Per the docs:

- **Explore**: "A fast, read-only agent optimized for searching and analyzing codebases." Uses Haiku for speed.
- **Plan**: "A research agent used during plan mode to gather context before presenting a plan." Read-only.
- **General-purpose**: "A capable agent for complex, multi-step tasks that require both exploration and action."

You can also create your own. Subagents are markdown files with YAML frontmatter, stored in `.claude/agents/` (project) or `~/.claude/agents/` (user). Documented frontmatter fields include `name`, `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `maxTurns`, `skills`, `mcpServers`, `hooks`, `memory`, `effort`, `background`, `isolation`, and `color`.

Use `/agents` inside Claude Code to manage them interactively.

### Plan mode

Plan mode is a read-only planning pass before Claude makes changes. Per the docs: "Plan Mode instructs Claude to create a plan by analyzing the codebase with read-only operations, perfect for exploring codebases, planning complex changes, or reviewing code safely."

Three ways to enter plan mode:

1. Press `Shift+Tab` twice during a session. You will see `⏸ plan mode on` at the bottom.
2. Start a session with `claude --permission-mode plan`.
3. Run a headless query with `claude --permission-mode plan -p "Analyze the auth system and suggest improvements"`.

Press `Ctrl+G` to open the proposed plan in your text editor for direct editing.

### Agent teams and the Agent SDK

Subagents coordinate within a single session. For cross-session coordination, Anthropic documents **agent teams**. For fully custom agents built on Claude Code's internals, there is the **Agent SDK**, which the docs describe as letting you "build your own agents powered by Claude Code's tools and capabilities, with full control over orchestration, tool access, and permissions."

## How Claude Code compares

The AI coding tool space in 2026 is crowded. Honest comparisons based on what each tool's docs actually say:

### Claude Code vs Cursor

Cursor is an IDE (a fork of VS Code). Claude Code is primarily a CLI, with an IDE extension as an alternative surface. If your workflow is IDE-first and you want deep editor integration (inline tab completion, visual diffs on every keystroke, @-mentions), Cursor is built for that. If you live in the terminal and want to pipe, script, and chain coding tasks like Unix utilities ("Pipe logs into it, run it in CI, or chain it with other tools," per the Claude Code docs), Claude Code is built for that.

Claude Code also ships a VS Code extension that "provides inline diffs, @-mentions, plan review, and conversation history directly in your editor," so you do not have to choose one or the other.

### Claude Code vs Codex CLI

OpenAI's Codex CLI is the closest shape match: also a CLI, also agentic, also runs on your machine. The differences are model lineage and the ecosystem around the CLI. Claude Code's docs document plugins, skills, hooks, MCP, subagents, agent teams, GitHub Actions integration, GitLab CI/CD integration, scheduled routines, and the Agent SDK as first-party features. Pick based on model preference and which ecosystem you want to build on.

### Claude Code vs Aider

Aider is an open-source terminal coding assistant with strong git integration. Similar surface, different philosophy. Aider has been around longer and has a simpler, more opinionated feature set. Claude Code's docs describe a broader surface area: four install targets, IDE plugins, a web interface, Bedrock/Vertex/Foundry support, and the plugin ecosystem. Aider is lean and focused, Claude Code is a platform.

## Pricing

Pulled from `claude.com/pricing`:

- **Free**: $0. Does not include Claude Code.
- **Pro**: $17/month annual or $20/month monthly. Claude Code is included.
- **Max**: From $100/month. Pro features plus "5x or 20x more usage than Pro," higher output limits, early access, and priority during high traffic.
- **Team**: $20/seat/month annual or $25/seat/month monthly (standard seat). Premium seat is $100/month annual or $125/month monthly. Includes Claude Code, SSO, admin controls.
- **Enterprise**: Seat price ($20) plus usage at API rates. Adds SCIM, audit logs, role-based access, compliance API, custom data retention, IP allowlisting, and a HIPAA-ready offering.

The setup docs confirm: "Claude Code requires a Pro, Max, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access."

## Five things to do after you install it

Based on the official docs, here is a sensible onboarding sequence.

### 1. Run `/init` to generate CLAUDE.md

The docs say `/init` "analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers." Refine from there. If you want a structured template, we built a [CLAUDE.md generator](https://developersdigest.tech/claudemd-generator) that walks you through the sections your project needs.

### 2. Try plan mode before shipping anything

Press `Shift+Tab` twice at the start of any non-trivial task. The docs are explicit: "A two-phase approach with planning produces better results than jumping straight to code." Plan mode uses read-only tools, gathers requirements, and proposes a plan you approve before execution.

### 3. Connect an MCP server

Pick one external tool you use every day (GitHub, Sentry, Linear, Stripe, a database) and connect it with `claude mcp add`. The difference between an agent that can only touch your filesystem and one that can read your production error logs is large. Browse the [MCP Directory](https://mcp.developersdigest.tech) for curated servers.

### 4. Save a workflow as a skill

The moment you catch yourself pasting the same 10-line playbook into chat twice, convert it to a skill. Either create the directory manually at `.claude/skills//SKILL.md` or use our [Skill Builder](https://skill.developersdigest.tech) to scaffold one from a short description. Skills you want to keep in your back pocket can live in [the Skills Directory](https://skills.developersdigest.tech).

### 5. Configure at least one hook

Start with something small. A `PostToolUse` hook that runs Prettier or ESLint after edits. A `PreToolUse` hook that blocks writes to `production.env`. A `SessionEnd` hook that logs session duration. The muscle memory of writing hooks unlocks the whole extensibility model.

## Where it falls short

Being honest about limitations, based on what the docs say and do not say.

**Cost for heavy users.** Pro at $20/month includes usage caps. Heavy users hit Max at $100/month or more. For teams using it as a primary coding tool, costs scale with seat count and usage.

**Context is finite.** Even with auto memory, CLAUDE.md, and subagents to preserve main-conversation context, you will hit limits on large codebases. The docs mention `/compact` and re-injection patterns, but long sessions still require care.

**Terminal-first bias.** The CLI is the most feature-complete surface. The VS Code extension, JetBrains plugin, desktop app, and web version all exist, but the CLI gets features first. If your whole team lives in JetBrains, you may feel one step behind.

**Plan mode does not prevent bad plans.** It prevents file changes during planning, but if the plan is wrong, you are still responsible for catching it. The docs say "a two-phase approach produces better results" and that is true on average, but not a free pass to stop reading what the agent proposes.

**Non-Anthropic models are not drop-in.** You can run Claude Code on Bedrock, Vertex, or Foundry, but those are alternate Claude deployments, not arbitrary models. If you want to run Claude Code against GPT, Gemini, or an open model, that is not what the docs describe.

## Start here

If you got this far and have not installed it, here is the install command one more time:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Then `cd` into a project and run `claude`. Let `/init` write a first pass of CLAUDE.md. Ask it to explain your codebase. Watch the agent loop run.

If you want to go deeper:

- The [CLAUDE.md Generator](https://developersdigest.tech/claudemd-generator) scaffolds a project memory file from a short description.
- The [MCP Directory](https://mcp.developersdigest.tech) catalogs MCP servers you can plug in.
- The [Skills Directory](https://skills.developersdigest.tech) collects shareable skills.
- The [Skill Builder](https://skill.developersdigest.tech) turns a one-line prompt into a SKILL.md you can drop into `.claude/skills/`.

The fastest way to understand Claude Code is to give it a real task you would otherwise do yourself and watch what it does. Start there.

## FAQ

### Is Claude Code free?

No. Claude Code requires a paid Anthropic account. Per the official pricing page, the free Claude.ai plan does not include Claude Code access. You need at least a Pro subscription ($17/month annual or $20/month monthly). Team, Enterprise, and Max plans also include Claude Code with additional features and higher usage limits.

### What is the difference between Claude Code and Claude?

Claude is Anthropic's large language model - the AI that powers conversations and reasoning. Claude Code is a coding agent built on top of Claude. While Claude answers questions in a chat interface, Claude Code is an agentic tool that can read your codebase, edit files, run terminal commands, make git commits, and integrate with external services through MCP. Think of Claude as the brain, Claude Code as the hands.

### Can Claude Code work offline?

No. Claude Code requires an internet connection to communicate with Anthropic's API. The agent runs locally on your machine and executes tools locally, but reasoning happens on Anthropic's servers. This is true for all installation methods (CLI, VS Code extension, JetBrains plugin, desktop app, and web).

### How do I give Claude Code context about my project?

Create a `CLAUDE.md` file in your project root. Run `/init` inside a Claude Code session to auto-generate one based on your codebase structure. This file should contain build commands, test instructions, coding conventions, and architecture notes. Keep it under 200 lines for best results. For larger projects, use `.claude/rules/` files with path-scoped instructions.

### Does Claude Code support languages other than JavaScript/TypeScript?

Yes. Claude Code is language-agnostic. It works with any language you can develop locally: Python, Go, Rust, Java, C++, Ruby, PHP, Swift, Kotlin, and more. The agent reads and writes files, runs terminal commands, and adapts to your project's tooling. If you can build and test it from the command line, Claude Code can work with it.

### How does Claude Code compare to GitHub Copilot?

Different tools for different workflows. GitHub Copilot is an autocomplete tool that suggests code as you type inside your editor. Claude Code is an agentic assistant that takes multi-step instructions, makes changes across multiple files, runs tests, and commits code. Copilot is inline completion, Claude Code is a conversation with a capable developer who can touch your whole project.

### Can I use Claude Code with my own API key?

Yes. You can authenticate through Anthropic directly (with a Pro/Max/Team/Enterprise account) or through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry with your own API credentials. Use `claude config` to set up your preferred authentication method.

### What is CLAUDE.md and why does it matter?

CLAUDE.md is a markdown file that gives Claude Code persistent context about your project. It loads automatically at the start of every session. Include your build commands, test commands, coding standards, architecture decisions, and any project-specific instructions. A good CLAUDE.md dramatically improves Claude Code's effectiveness because it does not have to rediscover your project structure every session.

## References

Every claim in this post is sourced from the following official documentation pages, fetched on 2026-04-19:

- [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview): product description, surfaces (terminal, VS Code, JetBrains, Desktop, Web), and capabilities (commits/PRs, MCP, skills, hooks, subagents, schedules, Unix piping).
- [code.claude.com/docs/en/setup](https://code.claude.com/docs/en/setup): system requirements, install commands for macOS/Linux/Windows/Homebrew/WinGet, authentication requirements, npm install option, and auto-update behavior.
- [code.claude.com/docs/en/memory](https://code.claude.com/docs/en/memory): CLAUDE.md file locations, precedence, import syntax, `.claude/rules/` scoping, and auto memory (v2.1.59+, 200-line/25KB load limit, storage location).
- [code.claude.com/docs/en/hooks](https://code.claude.com/docs/en/hooks): hook types (command, http, prompt, agent), lifecycle events, configuration structure, matcher patterns.
- [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills): SKILL.md structure, frontmatter fields, bundled skills, skill scopes, merging of custom commands into skills.
- [code.claude.com/docs/en/mcp](https://code.claude.com/docs/en/mcp): `claude mcp add` commands, installation scopes (local/project/user), OAuth flow, transport types.
- [code.claude.com/docs/en/subagents](https://code.claude.com/docs/en/subagents): built-in subagents (Explore, Plan, general-purpose), custom subagent frontmatter fields, `/agents` command.
- [code.claude.com/docs/en/common-workflows](https://code.claude.com/docs/en/common-workflows): plan mode details (`Shift+Tab` cycle, `--permission-mode plan`, `Ctrl+G` to edit plans), worktrees, session resume.
- [claude.com/pricing](https://claude.com/pricing): Free/Pro/Max/Team/Enterprise pricing and feature breakdown.


What Is Cursor? The AI Code Editor Explained (2026)
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
Cursor is the editor that made "coding with AI" feel like one coherent product rather than an autocomplete plugin stapled onto something else. It is built by Anysphere on a VS Code base, and in April 2026 the company says it is "trusted by over half of the Fortune 500 to accelerate development, securely and at scale."

This post is the plain-English answer to "what is Cursor and should I be using it." Every feature name, price, and claim here is checked against the current Cursor docs and pricing page as of April 2026. If you already use Cursor and want the production playbook, see the [hands-on Cursor guide](/blog/cursor-ai-code-editor-guide) for the companion piece.

## What Cursor Actually Is

At its core, Cursor is a fork of Visual Studio Code. If you open it cold, the window looks almost identical to VS Code. Your extensions, keybindings, themes, and `settings.json` carry over. Anysphere did not try to reinvent the editor chrome. They rebuilt the parts around it.

What you get on top of that familiar shell:

- A custom autocomplete model called **Tab** that predicts your next edit, not just your next token.
- An agentic chat called **Agent** that can read the codebase, run shell commands, edit files, and drive a browser.
- **Inline Edit**, a `Cmd+K` text-to-diff interface for targeted changes.
- **Composer 2**, Cursor's own frontier coding model, which Cursor describes as "a frontier model that is 4x faster than similarly intelligent models" and which "completes most turns in under 30 seconds."
- **Cloud agents** (formerly Background Agents) that run the same agent in an isolated cloud VM.
- **Bugbot**, a PR review agent that posts comments on GitHub.
- A project rules system under `.cursor/rules/` for per-repo context.

Cursor supports "every cutting-edge model from OpenAI, [Anthropic](/blog/anthropic-vs-openai-developer-experience), Gemini, xAI, and Cursor," per the landing page, and the docs list current options including Composer 2, GPT-5.4, Opus 4.6, Gemini 3 Pro, and Grok Code. You pick the model per chat, per agent, or let Auto route for you.

## The Four Ways You Actually Use It

Most developers interact with Cursor through four surfaces. The names matter because keybindings, billing, and docs use them exactly.

### 1. Tab (autocomplete)

Tab is the specialized autocomplete. From the docs: "Tab is Cursor's AI-powered autocomplete. It suggests code as you type, based on your recent edits, surrounding code, and linter errors."

Two things make it different from traditional autocomplete. First, it does multi-line edits: "Tab can modify multiple lines, add missing import statements, and suggest coordinated edits across related code." Second, after you accept a suggestion, hitting Tab again invokes "jump-in-file," which "predicts your next editing location and jumps there." You end up pressing Tab to move and edit in the same gesture.

### 2. Inline Edit (`Cmd+K`)

Inline Edit is for targeted, in-place changes. Select code, press `Cmd+K` on Mac or `Ctrl+K` on Windows/Linux, type what you want, press Return. Cursor writes the diff inline. You accept or reject.

Inline Edit also works in the integrated terminal - useful for conjuring a long CLI invocation you cannot remember. And if you want to ask about selected code instead of changing it, `Opt+Return` switches to question mode.

### 3. Agent chat (`Cmd+I` or `Cmd+L`)

Agent is the big one. The docs describe it as an assistant that "can complete complex coding tasks independently, run terminal commands, and edit code." The tools it has access to include semantic search, file and folder search, web search, fetch rules, read files, edit files, run shell commands, browser control, image generation, and asking the user clarifying questions.

There is a **Plan Mode** that "creates detailed implementation plans before writing any code. Agent researches your codebase, asks clarifying questions, and generates a reviewable plan you can edit before building." For bigger changes, Plan Mode is the thing that saves you from watching the agent confidently code the wrong architecture for ten minutes.

Cursor also auto-saves Checkpoints before significant changes, so you can roll back if an edit goes sideways. You can queue follow-up messages while the agent works, and `Cmd+Enter` bumps a message ahead of the queue.

### 4. Composer 2 (the model, not a separate UI)

Composer used to mean "the multi-file edit panel." In Cursor 2.0 (October 29, 2025) it became a proprietary coding model. Per Cursor's launch post, Composer is "a frontier model that is 4x faster than similarly intelligent models" and was "trained with tools including codebase-wide semantic search, making it much better at understanding and working in large codebases."

In practice, Composer 2 is one of the models you can pick inside Agent, alongside GPT-5.4, Opus 4.6, [Gemini](/blog/gemini-deep-research) 3 Pro, and Grok Code. It is optimized for fast turnarounds on real codebase tasks. When people say "Cursor's own model," this is what they mean.

## Cloud Agents (the feature formerly known as Background Agents)

Cloud agents are how Cursor escapes the constraint of your laptop. The docs are explicit: "Cloud agents leverage the same agent fundamentals but run in isolated environments in the cloud instead of on your local machine. (formerly called Background Agents.)"

The flow: an agent clones your repo from GitHub or GitLab, works on its own branch in a cloud VM, and pushes changes back. It can "build, test, and interact with the changed software" and "use computers to control the desktop and browser." It supports [MCP servers](/blog/complete-guide-mcp-servers), so you can give it access to external tools and data. The models used in cloud agents "always run in Max Mode."

You can launch cloud agents from Cursor Web, the desktop app, Slack, GitHub, Linear, or the API. Cursor 3.0 (April 2, 2026) added an Agents Window built specifically for running many of these in parallel and moving work between local, cloud, and SSH environments. Cursor 3.1 (April 13, 2026) added a Tiled Layout so you can "split your current view into panes to run and manage several agents in parallel."

In our [managed agents landscape research](/blog) we logged cloud agents running roughly $4.63 per easy PR in Max Mode, on top of the Pro subscription. That cost picture matters when you decide whether to use them instead of a local agent.

## Pricing (verified April 2026)

From cursor.com/pricing as of April 2026:

| Plan | Price | What you get |
|------|-------|--------------|
| Hobby | Free | No credit card, limited Agent requests, limited Tab completions |
| Pro | $20/month | Extended Agent limits, access to frontier models, MCPs/skills/hooks, cloud agents |
| Pro+ | $60/month | Everything in Pro plus 3x usage on all OpenAI, Claude, Gemini models |
| Ultra | $200/month | Everything in Pro plus 20x usage on those models, priority access to new features |
| Teams | $40/user/month | Everything in Pro plus collaboration and admin |
| Enterprise | Custom | Teams plus advanced controls and support |

Bugbot is billed separately: $40/user/month on Pro (up to 200 PRs/month), $40/user/month on Teams (all PRs), custom on Enterprise.

The old "500 premium requests for $20" plan from 2024 is gone. Pro is now metered with "extended limits" rather than a fixed request count, and frontier model usage above the Pro ceiling pushes you into Pro+ or Ultra. If you are tempted to compare to the [pricing](/blog/ai-coding-tools-pricing-2026) in our 2024 Cursor guide, use the table above. The numbers shifted.

## Rules: `.cursor/rules/` Is Current, Not `.cursorrules`

This is the one that trips people up. The current, documented format is the `.cursor/rules/` directory with `.md` or `.mdc` files. Not a single `.cursorrules` file.

From the docs:

- **Project Rules** live in `.cursor/rules/`, are version-controlled, and are scoped to one codebase.
- **User Rules** are global across all your Cursor projects, used by Agent.
- **Team Rules** are org-wide for Teams and Enterprise, managed in the dashboard.

`.mdc` files support frontmatter so you can declare when a rule applies:

```yaml
---
description: "Rule purpose"
alwaysApply: false
globs: [pattern]
---
```

There are four application modes: Always Apply, Apply Intelligently (the agent reads the description and decides), Apply to Specific Files (via glob), or Apply Manually when you `@`-mention the rule in chat. If you have an old `.cursorrules` file in a repo, it may still work, but new work should use `.cursor/rules/*.mdc` - that is what Cursor documents and what the team is building against.

## Cursor vs GitHub Copilot

The shortest honest answer: Copilot is an extension, Cursor is an editor.

GitHub Copilot lives inside VS Code, JetBrains, and increasingly every editor. You get autocomplete and a chat panel. In 2026 Copilot also has the Coding Agent, which accepts a GitHub issue and opens a PR from a cloud VM, and multi-model support (GPT-5.4, Claude Opus 4.6, Gemini, o3). Pricing starts at $10/month for Pro, $19 for Business, $39 for Pro+ and Enterprise, with 300 premium requests per month as the base and $0.04 overflow per request.

What Cursor has that Copilot does not:

- Tab, which predicts next-edit rather than next-token and jumps across files.
- A first-class Agent surface with Plan Mode, Checkpoints, queued messages, and browser control.
- Composer 2, the in-house coding model, tuned for the UI.
- Agents Window, Tiled Layout, Canvases - interface built around running multiple agents at once.

What Copilot has that Cursor does not:

- It lives inside the editor you already use, including JetBrains.
- Tight, boring, native integration with GitHub issues and PRs.
- A lower price floor.

The honest picking rule: if your team is already standardized on VS Code plus JetBrains and wants the safest procurement story, Copilot is the path of least resistance. If you want the editor where AI features ship first and feel most integrated, it is Cursor.

## Cursor vs Claude Code

Claude Code is a CLI agent from Anthropic, not an editor. It runs in your terminal, reads and edits your files, runs commands, and uses Claude models. You can also embed it in VS Code and JetBrains via plugins.

These two tools are not really direct competitors. They assume different defaults.

- **Cursor assumes you want an IDE.** You open a window, you see a file tree, you edit with a mouse and a keyboard, the AI is one surface among several.
- **Claude Code assumes the terminal is the interface.** It runs headlessly, composes with shell tools, is scriptable with `-p`, and tends to be used by developers who already live at a prompt.

Many developers use both. Cursor for "I am writing code, show me diffs I can review visually." Claude Code for "I need this agent to plan a migration across 40 files, run my tests, and commit if they pass - I will go grab coffee." Our deeper [Cursor vs Claude Code comparison](/blog/cursor-vs-claude-code-2026) walks through the trade-offs file by file.

## When to Reach for Cursor

Cursor is a good fit when:

- You already know VS Code and want a faster, AI-native version of the same editor.
- Your work is mostly front-end, full-stack, or product-engineering where you need to see diffs and rendered output to trust a change.
- You want Tab's multi-line, cross-file completions and are willing to pay for the quality.
- You are running multiple agents in parallel on different branches and want a real UI to track them.
- Your team is on GitHub and you want Bugbot posting on PRs.

It is less ideal when:

- You live in JetBrains and do not want to leave. Cursor is VS Code, not a universal plugin.
- You want a purely terminal-driven agent workflow with scripts and cron jobs. That is Claude Code territory.
- You need the lowest possible price and your usage is light. Copilot Pro at $10 is cheaper than Cursor Pro at $20.
- Your org has strict self-hosting rules. Cursor has self-hosted cloud agents as of March 2026, but Enterprise-only.

## Getting Started

Download the app from cursor.com. On first launch, sign in, let it import your VS Code extensions and settings, and pick a model. Composer 2 on Auto is a reasonable default.

From there:

1. Try Tab on an existing file. Make a small edit and watch it predict the ripple changes.
2. Select a function, press `Cmd+K`, say "add error handling and JSDoc." Accept or reject the diff.
3. Press `Cmd+I`, ask Agent to "refactor the auth module to use the new session API." Try Plan Mode first, review the plan, then let it build.
4. Add a `.cursor/rules/project.mdc` with your coding conventions. Future agent runs will pick them up automatically.
5. Launch a cloud agent from the Agents Window for a well-scoped task while you keep working locally.

That is the on-ramp. The ceiling is much higher than the floor. Teams on Ultra are running parallel agents across worktrees, wiring MCP servers into their internal APIs, and treating Cursor as an agent orchestration surface, not just an editor.

## The Bottom Line

Cursor in 2026 is a VS Code fork that has quietly become one of the most opinionated answers to "what should an AI-first editor look like." Tab is the best autocomplete in the industry. Agent with Plan Mode and Checkpoints is a sane default for editing real codebases. Composer 2 handles the common case faster than general-purpose frontier models. Cloud agents and the Agents Window let you run many of these in parallel when one is not enough.

It is not the cheapest option, it is not the only option, and it is not going to replace every tool you have. But if you want to understand what "AI coding" means when a team takes it seriously as a product rather than a feature, Cursor is the one to learn.

For a deeper walkthrough of the day-to-day workflow, see the [Cursor hands-on guide](/blog/cursor-ai-code-editor-guide). For the comparison to Anthropic's CLI agent, see [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026).

## Frequently Asked Questions

### Is Cursor free?

Cursor has a free Hobby tier with no credit card required. You get limited Agent requests and Tab completions. For extended usage, Pro starts at $20/month, Pro+ is $60/month with 3x usage limits, and Ultra is $200/month with 20x usage and priority access to new features.

### Is Cursor just VS Code with AI?

Cursor is built on the VS Code base, but it is not just a plugin. Anysphere forked VS Code and rebuilt the AI integration at the core. This means Tab (autocomplete) can predict multi-line edits and jump across files, Agent has native access to file editing and shell commands, and features like Plan Mode and Checkpoints are designed for real codebase work rather than bolted on afterward.

### Is Cursor better than GitHub Copilot?

They serve different defaults. Copilot is an extension that lives inside VS Code, JetBrains, and other editors. Cursor is an editor where AI is the primary interface. Cursor's Tab autocomplete predicts next-edit rather than next-token, and Agent has more integrated tools. Copilot is cheaper ($10/month vs $20/month) and works in JetBrains. The right choice depends on whether you want an AI-enhanced plugin or an AI-first editor.

### Can I use my VS Code extensions in Cursor?

Yes. Cursor imports your VS Code extensions, keybindings, themes, and settings.json on first launch. Since Cursor is a fork of VS Code, most extensions work without modification. You keep your existing workflow while gaining Cursor's AI features.

### What is Composer 2?

Composer 2 is Cursor's proprietary coding model, launched with Cursor 2.0 in October 2025. Cursor describes it as "a frontier model that is 4x faster than similarly intelligent models" and trained with tools including codebase-wide semantic search. In practice, it is one of the model options inside Agent, alongside GPT-5.4, Claude Opus 4.6, Gemini 3 Pro, and Grok Code.

### What are Cursor Cloud Agents?

Cloud agents (formerly Background Agents) run the same agent capabilities in an isolated cloud VM instead of your local machine. The agent clones your repo from GitHub or GitLab, works on its own branch, builds and tests the code, and pushes changes back. You can launch cloud agents from Cursor Web, the desktop app, Slack, GitHub, Linear, or the API. They always run in Max Mode, so costs can add up.

### Is Cursor safe to use with proprietary code?

Cursor offers Privacy Mode, which disables cloud storage of your code. For Teams and Enterprise tiers, Cursor provides additional admin controls and compliance features. The self-hosted cloud agents option became available in March 2026 for Enterprise customers with strict data residency requirements. Review the current privacy documentation at cursor.com for your organization's specific needs.

### Should I use Cursor or Claude Code?

They assume different workflows. Cursor is an IDE where you see files, diffs, and agent output visually. Claude Code is a CLI agent that runs in your terminal and composes with shell tools. Many developers use both: Cursor for visual editing and reviewing changes, Claude Code for headless migrations and automated workflows. See [Cursor vs Claude Code](/blog/cursor-vs-claude-code-2026) for a detailed comparison.

## References

- [Cursor homepage](https://cursor.com/)
- [Cursor pricing page](https://cursor.com/pricing)
- [Cursor features page](https://cursor.com/features)
- [Cursor docs home](https://cursor.com/docs)
- [Cursor Agent overview (docs)](https://cursor.com/docs/agent/overview)
- [Cursor Tab overview (docs)](https://cursor.com/docs/tab/overview)
- [Cursor Inline Edit (docs)](https://cursor.com/docs/inline-edit)
- [Cursor Background Agents / Cloud Agents (docs)](https://cursor.com/docs/background-agent)
- [Cursor Rules (docs)](https://cursor.com/docs/context/rules)
- [Cursor 2.0 and Composer launch post](https://cursor.com/blog/2-0)
- [Cursor changelog](https://cursor.com/changelog)
- [GitHub Copilot plans](https://github.com/features/copilot/plans)
- [Anthropic Claude Code](https://www.anthropic.com/claude-code)


What Is the Model Context Protocol? A 2026 Primer
Developers Digest — Sun, 19 Apr 2026 00:00:00 GMT
## Why a protocol, not another plugin format

Every AI product has the same integration problem. The model needs to read a file, query a database, call an API, or pull a design from Figma. For most of 2023 and 2024, every vendor solved this with a proprietary plugin system. ChatGPT had plugins. Each IDE shipped its own tool-calling hooks. Every framework invented a different function-calling convention. The result was an N-by-M mess: M tools had to be reimplemented for N models.

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

The Model Context Protocol (MCP), announced by [Anthropic](/blog/anthropic-vs-openai-developer-experience) on November 25, 2024 and since adopted by Claude, ChatGPT, Cursor, VS Code, Zed, Replit, and others, is the attempt to end that mess. It is not a plugin store. It is a wire-level protocol based on JSON-RPC 2.0, modeled loosely on the Language Server Protocol (LSP), and deliberately transport-agnostic.

If you have used `tsserver` through VS Code, you already know the shape. LSP lets any editor talk to any language by agreeing on a JSON-RPC contract. MCP does the same thing for LLM applications and their tools. Write a server once, and any MCP-compatible host can use it.

This primer is written for developers who want to understand the protocol itself: the methods, the lifecycle, the transports, the security model. Everything below is cross-referenced against the [2025-06-18 specification](https://modelcontextprotocol.io/specification/2025-06-18).

## The protocol in one paragraph

MCP is JSON-RPC 2.0 over a duplex transport, with stateful sessions and capability negotiation. There are three roles. The **host** is the LLM application the user interacts with (Claude Desktop, [Cursor](/blog/what-is-cursor-ai-code-editor-2026), Zed). The **client** is a connector inside the host, responsible for exactly one server. The **server** is the external process that exposes context and capabilities. Servers offer three primitive types - tools, resources, and prompts - and clients offer three of their own - sampling, roots, and elicitation. Every message is a UTF-8 JSON-RPC request, notification, or response.

That is the whole thing. The rest is detail.

## Transports

The spec currently defines two standard transport mechanisms, with custom transports allowed.

**stdio** is the default. The client spawns the server as a subprocess, writes JSON-RPC messages to `stdin`, and reads them from `stdout`. Each message is newline-delimited, with no embedded newlines. `stderr` is reserved for logging. This is what every local server on your machine uses. The spec says clients `SHOULD` support stdio whenever possible, and it is the right choice for anything running on the same host.

**Streamable HTTP** is the remote transport. It was introduced in the 2025-03-26 revision of the spec and replaces the older HTTP+SSE transport from the 2024-11-05 revision, which is now deprecated. A server exposes a single HTTP endpoint (conventionally `/mcp`) that accepts both POST and GET. The client sends JSON-RPC messages via POST. The server can respond with either `Content-Type: application/json` for a single response, or `Content-Type: text/event-stream` to open an SSE stream for multiple messages. The client can also open a GET stream to let the server push unsolicited notifications.

Streamable HTTP brings two things the old HTTP+SSE transport lacked. First, sessions. On initialization, the server can issue a session ID in an `Mcp-Session-Id` response header, and the client echoes it back on every subsequent request. If the server returns `404` with that session ID, the client knows to re-initialize. Second, resumability. Servers can attach `id` fields to SSE events, and clients can reconnect with a `Last-Event-ID` header to replay messages lost during a network hiccup.

One gotcha. When using HTTP, the client `MUST` include an `MCP-Protocol-Version` header on every request after initialization, for example `MCP-Protocol-Version: 2025-06-18`. If the server gets an unknown version, it returns `400 Bad Request`. If the header is missing, the server assumes `2025-03-26` for backwards compatibility.

## The lifecycle

Every session goes through three phases: initialization, operation, shutdown.

Initialization is a handshake. The client sends an `initialize` request with the protocol version it supports, its capabilities, and its `clientInfo`. The server responds with its own `protocolVersion`, `capabilities`, `serverInfo`, and an optional `instructions` string. The client then sends a `notifications/initialized` notification. Only after that can normal operations begin.

Here is a real `initialize` request from the spec:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {},
      "elicitation": {}
    },
    "clientInfo": {
      "name": "ExampleClient",
      "title": "Example Client Display Name",
      "version": "1.0.0"
    }
  }
}
```

And the server response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "logging": {},
      "prompts": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "tools": { "listChanged": true }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}
```

Capability negotiation is how MCP stays flexible without becoming a kitchen sink. If the server does not declare `prompts`, the client must not call `prompts/list`. If the server declares `resources` without `subscribe`, the client cannot call `resources/subscribe`. This is how the protocol grows features without breaking old implementations.

Shutdown is not a message. For stdio, the client closes the server's `stdin` and waits for the subprocess to exit, escalating to `SIGTERM` and `SIGKILL` if needed. For HTTP, you close the connection. A well-behaved client also sends `HTTP DELETE` with the session ID to let the server clean up.

## The three server primitives

Everything a server offers falls into one of three buckets. The distinction matters because it maps to who is in control.

### Tools are model-controlled

Tools are functions the LLM can call. The spec is blunt: "Tools in MCP are designed to be model-controlled, meaning that the language model can discover and invoke tools automatically." The client lists them with `tools/list`, the model picks one, and the client invokes it with `tools/call`.

A tool definition has a `name`, optional `title`, `description`, `inputSchema` (JSON Schema for arguments), and optional `outputSchema` and `annotations`. Tool results come back in a `content` array that can mix text, images, audio, resource links, and embedded resources. An `isError: true` flag signals tool execution failures, distinct from JSON-RPC protocol errors.

A tool call looks like this:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "New York" }
  }
}
```

Annotations are worth calling out. Fields like `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` let servers describe what a tool does. The spec is explicit that clients `MUST` treat annotations as untrusted unless the server itself is trusted. A malicious server can claim a tool is read-only. Your host application is responsible for getting user consent regardless.

### Resources are application-driven

Resources are readable data. Think files, database rows, API responses, log entries. Each resource has a URI, and the client can call `resources/list` to enumerate them, `resources/read` to fetch one, and `resources/templates/list` to discover parameterized URIs using RFC 6570 templates.

Here is a read request and response:

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": { "uri": "file:///project/src/main.rs" }
}
```

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "contents": [{
      "uri": "file:///project/src/main.rs",
      "mimeType": "text/x-rust",
      "text": "fn main() {\n    println!(\"Hello world!\");\n}"
    }]
  }
}
```

Resources support subscriptions. A client calls `resources/subscribe` with a URI and receives `notifications/resources/updated` whenever the underlying data changes. There is also `notifications/resources/list_changed` for catalog-level updates. The protocol registers a few URI schemes (`https://`, `file://`, `git://`) and leaves the door open for custom schemes.

The key distinction is control. Tools are model-controlled. Resources are application-driven. The host decides how to surface resources to the user: a tree view, a filter UI, or automatic inclusion based on heuristics. The model does not reach out and grab resources on its own.

### Prompts are user-controlled

Prompts are templated messages meant to be triggered by the user, typically as slash commands. A server lists them with `prompts/list` and returns their content with `prompts/get`, substituting any arguments the user provided. A prompt response is an array of messages, each with a `role` (user or assistant) and `content` (text, image, audio, or embedded resource).

This is the primitive that powers slash commands like `/code_review` in a chat UI. The user picks the prompt, the server fills it with context, and the resulting messages become the start of a conversation.

## Client primitives, briefly

Servers can ask the client for three things. **Sampling** lets the server request an LLM completion from the host, enabling agentic behaviors without the server needing its own API key. **Roots** let the server ask which filesystem or URI boundaries it is allowed to operate in. **Elicitation**, added in 2025-06-18, lets the server ask the user a direct question mid-session.

These are opt-in via capability negotiation and gated by user consent. The spec is explicit that users `MUST` explicitly approve any sampling request and should be able to see and edit the prompt before it is sent.

## Building a server in ~30 lines

The Python SDK, adapted from the official [python-sdk README](https://github.com/modelcontextprotocol/python-sdk), reduces the whole thing to this:

```python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run(transport="stdio")
```

FastMCP introspects the function signature, generates the `inputSchema`, and wires up `tools/list`, `tools/call`, `resources/list`, and `resources/read` automatically. Run it with `uv run mcp dev server.py` to test against the MCP Inspector.

The TypeScript SDK is in a similar place, with a v1.x stable release and v2 in pre-alpha. Both SDKs support stdio and Streamable HTTP transports out of the box. For HTTP, you import a middleware package for your framework (Express, Hono, Node.js) and mount the MCP endpoint.

## Security model

MCP delegates enforcement to the host but ships with a clear set of `MUST` and `SHOULD` requirements. The four principles:

1. **User consent and control.** Users must consent to every data access and tool invocation. Hosts must provide a UI to review and authorize.
2. **Data privacy.** Hosts must not transmit resource data elsewhere without consent.
3. **Tool safety.** Tools are arbitrary code execution. Descriptions and annotations must be treated as untrusted unless they come from a trusted server.
4. **LLM sampling controls.** Every sampling request is user-approved, and users should be able to see and modify the prompt.

For HTTP transports, authorization is OAuth 2.1 based. MCP servers `MUST` implement OAuth 2.0 Protected Resource Metadata (RFC 9728) and return a `WWW-Authenticate` header on `401` responses pointing to `/.well-known/oauth-protected-resource`. Clients `MUST` use Resource Indicators (RFC 8707) to bind tokens to a specific MCP server, and `MUST` implement PKCE. Dynamic Client Registration (RFC 7591) is `SHOULD`-level, which matters because it is the piece that makes new server onboarding seamless. For stdio transports, authorization is explicitly out of scope: you use environment variables.

Token passthrough is forbidden. If an MCP server calls an upstream API, it uses a separate token issued for that upstream. The MCP server must never forward a client-issued token downstream. This closes the confused deputy class of attacks.

## How MCP differs from what came before

**ChatGPT plugins** were a manifest plus an OpenAPI spec, polled over HTTPS. There was no lifecycle, no capability negotiation, no subscriptions, no bidirectional messaging, and no primitive beyond tool calls. The ecosystem was locked to one vendor. MCP is the portable version.

**Native tool calling** (the `tools` parameter in Anthropic's API or OpenAI's [function calling](/blog/mcp-vs-function-calling)) is a model capability, not a protocol. The application defines tools in-process, sends them with every request, and executes them locally. MCP sits one layer above: it standardizes how an application acquires those tool definitions from an external process in the first place. The two compose. Claude Code uses native tool calling to invoke tools, and it gets many of those tools from MCP servers.

**Cursor rules** and similar per-editor context files are static. They bolt instructions into the system prompt. MCP is dynamic: a server can expose live resources, subscribe to updates, and push notifications when the world changes.

## Where the protocol is going

The spec moves on a roughly quarterly cadence. The 2024-11-05, 2025-03-26, and 2025-06-18 revisions each added meaningful surface area (HTTP+SSE, Streamable HTTP plus OAuth, elicitation plus structured tool output). Anthropic donated the protocol to a neutral Agentic AI Foundation in 2025, which should accelerate governance maturity.

Public roadmap items under discussion include richer streaming for long-running tool calls, better cancellation semantics, standardized telemetry, and an official registry for server discovery. If you build in this space, follow the [specification repository](https://github.com/modelcontextprotocol/specification) on GitHub. The TypeScript schema in `schema/YYYY-MM-DD/schema.ts` is the source of truth that the human-readable spec is generated from.

## What to build next

If you are new to MCP, start by consuming it. Install the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), point it at an existing stdio server like `@modelcontextprotocol/server-filesystem`, and watch the JSON-RPC traffic. You will understand the protocol faster by reading the wire than by reading the spec.

Then write a server. Pick the smallest internal tool your team relies on - a health check, a deploy trigger, a query runner - and expose it with FastMCP or the TypeScript SDK. Thirty lines gets you a working server. From there, add a resource, add a subscription, swap stdio for Streamable HTTP, add OAuth. Each step maps to one section of the spec.

The protocol is small on purpose. That is its whole advantage.

## References

- [Model Context Protocol specification, 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18)
- [Model Context Protocol specification, 2025-03-26](https://modelcontextprotocol.io/specification/2025-03-26)
- [MCP introduction](https://modelcontextprotocol.io/introduction)
- [Transports specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
- [Lifecycle specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle)
- [Authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization)
- [Tools concept](https://modelcontextprotocol.io/docs/concepts/tools)
- [Resources concept](https://modelcontextprotocol.io/docs/concepts/resources)
- [Prompts concept](https://modelcontextprotocol.io/docs/concepts/prompts)
- [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Anthropic announcement, November 25 2024](https://www.anthropic.com/news/model-context-protocol)
- [Anthropic donation to Agentic AI Foundation](https://www.anthropic.com/news/donating-the-model-context-protocol-and-establishing-of-the-agentic-ai-foundation)
- [Why MCP moved from SSE to Streamable HTTP](https://blog.fka.dev/blog/2025-06-06-why-mcp-deprecated-sse-and-go-with-streamable-http/)

## FAQ

### What is the Model Context Protocol (MCP)?

MCP is a JSON-RPC 2.0 protocol that standardizes how LLM applications connect to external tools, data sources, and prompts. Instead of each AI product building proprietary plugin systems, MCP provides a universal wire format. Write an MCP server once and it works with Claude, ChatGPT, Cursor, VS Code, [Zed](/blog/zed-agentic-ide), and any other MCP-compatible host. It is modeled on the Language Server Protocol (LSP) that powers IDE language integrations.

### How is MCP different from function calling?

Function calling is a model capability where you define tools in your application code and send them with each API request. MCP sits one layer above: it standardizes how your application discovers and acquires tool definitions from external processes. The two compose. Claude Code uses native function calling to invoke tools, and many of those tool definitions come from MCP servers running as separate processes.

### What are the three MCP server primitives?

MCP servers expose three primitive types. **Tools** are functions the model can call autonomously. **Resources** are readable data like files, database rows, or API responses that the application decides when to surface. **Prompts** are templated messages triggered by the user, typically as slash commands. The distinction maps to control: tools are model-controlled, resources are application-driven, prompts are user-controlled.

### How do I build an MCP server?

The Python SDK with FastMCP reduces a working server to about 30 lines. Decorate functions with `@mcp.tool()` or `@mcp.resource()`, and FastMCP automatically generates the JSON Schema, wires up the protocol methods, and handles the transport. Run it with `uv run mcp dev server.py` to test against the MCP Inspector. The TypeScript SDK offers similar ergonomics. Both support stdio for local servers and Streamable HTTP for remote servers.

### What transports does MCP support?

MCP defines two standard transports. **stdio** is the default for local servers: the client spawns the server as a subprocess and exchanges newline-delimited JSON-RPC over stdin/stdout. **Streamable HTTP** is for remote servers: the client POSTs JSON-RPC to a single endpoint and receives responses via JSON or SSE streams. Streamable HTTP replaced the older HTTP+SSE transport in the 2025-03-26 spec revision and adds session management plus resumability.

### Is MCP secure?

MCP delegates enforcement to the host application but defines clear security requirements. Users must consent to every data access and tool invocation. Hosts must provide UI to review and authorize requests. Tool annotations like `destructiveHint` must be treated as untrusted unless the server itself is trusted. For HTTP transports, authorization uses OAuth 2.1 with PKCE and resource indicators. Token passthrough is explicitly forbidden to prevent confused deputy attacks.

### Which AI tools support MCP?

As of 2026, MCP is supported by Claude Desktop, Claude Code, ChatGPT, Cursor, VS Code (via extension), Zed, Replit, and many open-source LLM applications. Anthropic donated the protocol to the neutral Agentic AI Foundation in 2025, which has accelerated adoption. The ecosystem includes thousands of community-built servers for databases, APIs, file systems, and developer tools.

### How do I test an MCP server?

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), an official debugging tool that connects to any MCP server and lets you browse tools, resources, and prompts, invoke them manually, and watch the raw JSON-RPC traffic. For Python servers, run `uv run mcp dev server.py` to launch with the Inspector. For TypeScript servers, use `npx @modelcontextprotocol/inspector`. Watching the wire protocol is the fastest way to understand how MCP works.


AI Coding Tools Pricing in Q2 2026: What Actually Changed and Where Costs Surprise Teams
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
Pricing is where most AI coding evaluations go wrong.

Teams compare headline monthly plans, then discover the actual cost function lives in:

- request ceilings,
- premium request pools,
- routing behavior,
- and cloud execution defaults.

This Q2 2026 update focuses on what changed materially and what to watch in production. For a side-by-side view of API rates rather than seat plans, our [AI API pricing comparator](/pricing) keeps the per-token numbers up to date across providers.

## Q2 2026 Snapshot (Official Plan Surfaces)

### Anthropic Claude (Claude Code via Claude plans)

For cost context, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) alongside [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); together they separate sticker price from the operational habits that make agent work expensive.

- Max 5x: $100/month
- Max 20x: $200/month
- Framing: usage multiplier vs Pro plan session capacity.

Operational caveat from support docs: Pro/Max usage is shared across Claude and [Claude Code](/blog/what-is-claude-code-complete-guide-2026), and environment key configuration can route usage to API billing.

### Cursor

Current public [pricing](/blog/ai-coding-tools-pricing-2026) page shows:

- Hobby Free
- Pro: $20/month
- Pro+: $60/month
- Ultra: $200/month

[Cursor](/blog/what-is-cursor-ai-code-editor-2026) also explicitly advertises model-usage multipliers on higher plans for frontier-model usage.

### GitHub Copilot

Current docs surface:

- [Copilot](/blog/github-copilot-coding-agent-cli-2026) Pro: $10/month
- Copilot Pro+: $39/month
- Business: $19/seat/month
- Enterprise: $39/seat/month

Copilot docs also make premium request pools explicit and document paid add-on purchase for additional premium requests.

### OpenAI Codex

OpenAI developer docs position Codex as included with ChatGPT Plus, Pro, Business, Edu, or Enterprise (subject to workspace admin setup in some enterprise contexts).

Codex product updates through 2025-2026 also introduced major packaging changes around desktop app rollout and broad access windows.

## What Changed Recently (High Signal)

1. Codex packaging matured from preview-era cloud agent to broad client surface (CLI, IDE, app, web).
2. Codex app launch introduced explicit multi-agent parallelism UX.
3. GitHub Copilot documentation now foregrounds premium-request accounting and model access tiers.
4. Cursor expanded clear tiering for heavy usage with Pro+, Ultra multipliers.
5. Anthropic support docs clarified plan-vs-API routing details that have direct billing impact.

These changes make "same monthly price" comparisons less useful than workflow-aware cost modeling.

## The Four Cost Traps Teams Keep Hitting

### 1) Authentication trap (Claude side)

If your environment is configured with API key auth when you think you are using included plan capacity, you can accidentally switch cost models.

Action:
- Standardize auth profile per environment.
- Add startup checks to avoid accidental key routing.

### 2) Premium-request blindness (Copilot side)

Copilot plan docs separate base plan price from premium-request pool behavior.

Action:
- Track premium-request burn weekly.
- Reserve premium models for high-value tasks.

### 3) Tier multiplier confusion (Cursor side)

Cursor plans communicate multipliers for model usage, but teams often budget as if each seat has unlimited equivalent capacity.

Action:
- Model usage by role: heavy builders vs occasional users.
- Buy higher tiers only where utilization justifies it.

### 4) Cloud-task externalities (Codex side)

Cloud delegation improves throughput but may add hidden overhead from environment setup, dependency fetches, and repeated sandbox startup patterns.

Action:
- Reuse environment configuration aggressively.
- Define domain/network policy and setup scripts carefully.

## A Better Budgeting Framework

Do not budget by tool. Budget by workflow lane.

### Lane A: Fast local implementation

Characteristics:
- frequent short loops,
- heavy review,
- many small edits.

Good fit:
- lower-latency local-first agent modes.

### Lane B: Long-running delegated tasks

Characteristics:
- background execution,
- parallel threads,
- issue-to-PR flow.

Good fit:
- cloud-task oriented agent systems.

### Lane C: High-governance enterprise work

Characteristics:
- policy controls,
- auditability,
- seat-level administration.

Good fit:
- enterprise-grade controls with predictable per-seat governance.

Assign each engineer's work mix to lanes first, then choose plan tiers. This prevents overbuying expensive tiers for users who do not consume them.

## Reaction Signal From Power Users (How to Use It)

Community reactions in tool-specific forums usually cluster around three pain points:

1. Pricing predictability and "included" usage interpretation.
2. Sudden perceived shifts in throughput or effective limits.
3. Difficulty mapping model access to real output quality gains.

Use these signals as monitoring prompts, not truth sources:

- Instrument usage internally.
- Validate with your own team's workload.
- Re-evaluate every 30 days because packaging changes quickly.

## Recommended Playbook for Dev Teams

1. Standardize one primary tool per team for 30 days.
2. Keep one secondary tool for overflow/specialized lanes.
3. Track three metrics weekly:
- Cost per merged PR
- Median time-to-first-working-solution
- Rework rate after AI-generated changes
4. Re-tier seats monthly based on actual usage, not preference.

This is where the biggest cost wins come from.

## Frequently Asked Questions

### How much does Claude Code cost?

Claude Code is included with Claude Max plans. Max 5x costs $100/month and Max 20x costs $200/month. The usage multiplier refers to session capacity compared to the Pro plan. Usage is shared across Claude chat and Claude Code, so heavy Claude Code usage reduces available Claude chat capacity. Teams can also use API billing by configuring environment keys, which switches to pay-per-token pricing.

### Is GitHub Copilot worth the price?

GitHub Copilot Pro costs $10/month and offers solid value for basic autocomplete and inline suggestions. Pro+ at $39/month adds premium request pools for access to frontier models. For teams, Business at $19/seat/month includes admin controls, and Enterprise at $39/seat/month adds policy governance. The value depends on your usage pattern - light users get full value from the base tier, while power users may exhaust premium request pools quickly.

### What is the cheapest AI coding tool?

GitHub Copilot Pro at $10/month is the cheapest paid option with unlimited basic suggestions. Cursor's Hobby tier is free with limited requests. For heavy agentic usage, cost-per-output varies significantly - a $200/month Claude Max subscription may cost less per merged PR than a $20/month Cursor Pro subscription if you hit usage limits. Budget by workflow, not sticker price.

### Why do AI coding tools have different pricing models?

Pricing models reflect different cost structures. Seat-based pricing (Copilot, Cursor) provides predictable team budgets. Usage multipliers (Claude Max, Cursor tiers) account for varying consumption patterns. Premium request pools (Copilot) allow tiered access to expensive frontier models. Cloud execution (Codex) may add infrastructure overhead. Understanding your team's usage pattern helps choose the right model.

### How do I avoid surprise AI coding tool bills?

Four common traps: (1) Authentication confusion - Claude Code may route to API billing if environment keys are misconfigured. (2) Premium request blindness - Copilot users exhaust premium pools without realizing it. (3) Tier multiplier confusion - Cursor users assume unlimited capacity when plans have usage multipliers. (4) Cloud task overhead - Codex cloud execution adds setup and dependency costs. Track usage weekly and standardize authentication profiles.

### Which AI coding tool is best for teams?

For governance-focused enterprises, GitHub Copilot Enterprise offers audit trails and policy controls. For high-autonomy workflows, Claude Code Max 20x provides extended session capacity. For mixed workflows, Cursor Pro+ balances cost and capability. Assign engineers to workflow lanes (fast local edits vs. long-running delegated tasks vs. governance-heavy work), then match tools to lanes rather than standardizing one tool across all use cases.

### Can I use multiple AI coding tools together?

Yes, and many power users do. A common pattern: use a lower-cost tool (Copilot Pro, Cursor Free) for routine autocomplete, and a higher-tier agentic tool (Claude Code Max, Codex) for complex multi-file tasks. This optimizes cost per task type. Track cost-per-merged-PR across tools to validate whether the multi-tool approach actually saves money for your workflow.

### How often does AI coding tool pricing change?

Expect material pricing or packaging changes every 30-60 days. Q2 2026 saw Codex packaging mature from preview to broad client access, GitHub Copilot foreground premium-request accounting, Cursor expand tiering with Pro+ and Ultra, and Anthropic clarify plan-vs-API routing. Re-evaluate your tool selection monthly - the pricing landscape changes faster than annual planning cycles assume.

## Sources (Docs + Announcements)

- Anthropic: [Max plan pricing](https://claude.com/pricing/max)
- Anthropic Support: [Pro/Max plan behavior in Claude Code](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- Cursor: [Pricing](https://cursor.com/en-US/pricing)
- GitHub Docs: [Copilot plans](https://docs.github.com/en/copilot/get-started/plans)
- GitHub: [Copilot plans and pricing](https://github.com/features/copilot/plans)
- OpenAI: [Introducing the Codex app](https://openai.com/index/introducing-the-codex-app/)
- OpenAI: [Codex GA announcement](https://openai.com/index/codex-now-generally-available/)
- OpenAI Developers: [Codex cloud](https://developers.openai.com/codex/cloud)
- OpenAI Developers: [API changelog](https://developers.openai.com/api/docs/changelog)

## Related apps

- [Agent Hub](https://agenthub.developersdigest.tech) - One control panel for Claude Code, Codex, Gemini, Cursor, and 10+ AI coding harnesses. Desktop app for Mac.
- [Skills Pro](https://skills.developersdigest.tech/pricing) - Premium tier for the Skills marketplace. Unlock pro skills, private collections, and team sharing.

## Related

- [Subscribe to DevDigest on YouTube](https://www.youtube.com/@DevelopersDigest?sub_confirmation=1) for hands-on walkthroughs


Aider vs Claude Code in 2026: Git-First Open Source vs Subagent Runtime
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
Aider and [Claude Code](/blog/what-is-claude-code-complete-guide-2026) are both terminal-native AI coding tools, but they optimize for different control models.

- Aider is git-first and model-agnostic by design.
- Claude Code is runtime-first with [subagents](/blog/claude-code-sub-agents), hooks, and deeper workflow orchestration.

In 2026, teams choosing between them should compare operational behavior, not just model quality. For the wider category map, start with [what an AI coding agent is](/blog/what-is-an-ai-coding-agent-2026) and the [AI coding tools comparison matrix](/blog/ai-coding-tools-comparison-matrix-2026). If you want a fast recommendation tailored to how you actually work, our [AI coding agent picker](/which-tool) returns one in under a minute.

## Core Architectural Difference

### Aider: Git as the primary contract

Aider's documentation emphasizes commit-centric operation:

- When Aider edits files, it commits those changes with descriptive commit messages.
- It exposes in-chat git operations (`/diff`, `/undo`, `/commit`, `/git`).
- It supports a wide provider matrix and explicit model routing patterns.

This is ideal if your top concern is clean auditability in git history and easy rollback.

### Claude Code: Agent runtime as the primary contract

Claude Code's docs emphasize agent controls:

- Subagents with tool inheritance and allowlist/denylist controls.
- Hook lifecycle events, including task-completion quality gates.
- Team-shared settings and policy patterns in project config.

This is ideal if your top concern is controlled automation across complex coding workflows.

If this is the side of the comparison you care about, the [Claude Code agent teams playbook](/blog/claude-code-agent-teams-subagents-2026) explains how subagents, MCP, hooks, and skills fit together in a real workflow.

## Model Flexibility and Provider Strategy

### Aider

Aider's model docs show explicit examples for OpenAI, [Anthropic](/blog/anthropic-vs-openai-developer-experience), OpenRouter, and others. This matters for teams that want provider arbitrage or local model experimentation.

A common pattern:

- cheaper model for broad exploration,
- premium model for final code generation and refactor correctness,
- same CLI workflow across both.

### Claude Code

Claude Code is tightly optimized around Anthropic's runtime and workflow semantics. Subagents can target model aliases (`haiku`, `sonnet`, `opus`) and support model override behavior at invocation time.

This makes model changes operationally simple inside the same system, but less provider-neutral than Aider.

## Governance and Safety Controls

### Aider governance strength

- Every edit is naturally reviewable through commit granularity.
- Rollback is immediate via git operations.
- Strong fit for teams that already enforce strict branch and commit discipline.

### Claude Code governance strength

- Tool-capability boundaries per subagent profile.
- Hook-based quality checks that can block completion when gates fail.
- Better suited for teams needing policy-aware automation beyond plain file edits.

## Cost Behavior in Practice

Cost behavior is often misinterpreted as "tool quality" issues.

### Aider cost profile

Aider lets you route to any provider/model explicitly, which can reduce [costs](/blog/ai-coding-tools-pricing-comparison) for teams willing to manage model selection actively.

### Claude Code cost profile

Claude Code plan and support docs make clear that Pro/Max usage is shared across Claude and Claude Code. They also note routing pitfalls when API-key auth is active.

In both tools, strong process design beats ad hoc prompting for cost efficiency. The [AI coding tools pricing guide](/blog/ai-coding-tools-pricing-2026) is the broader cost baseline, and the [Claude Code usage limits playbook](/blog/claude-code-usage-limits-playbook-2026) covers the operational side for Anthropic-heavy teams.

## Where Each Tool Wins in 2026

### Use Aider when

- You want maximum provider/model flexibility.
- You prioritize commit-level traceability and rollback.
- Your team already runs mature git workflows and prefers explicit manual control.

### Use Claude Code when

- You need subagents, hooks, and richer runtime automation.
- You want policy-aware delegation and teammate-style workflows.
- You optimize for autonomous execution with configurable guardrails.

## A Pragmatic Team Setup

Many advanced teams run both:

- Aider for low-friction edits and highly auditable git-first changes.
- Claude Code for multi-step autonomous tasks, policy gates, and complex orchestration.

Treat them as complementary execution modes, not mutually exclusive tools.

## Sources

- Aider Docs: [Git integration](https://aider.chat/docs/git.html)
- Aider Docs: [Models and API keys](https://aider.chat/docs/troubleshooting/models-and-keys.html)
- Anthropic Docs: [Claude Code getting started](https://code.claude.com/docs/en/getting-started)
- Anthropic Docs: [Subagents](https://code.claude.com/docs/en/sub-agents)
- Anthropic Docs: [Hooks](https://code.claude.com/docs/en/hooks)
- Anthropic Support: [Using Claude Code with Pro/Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)

---

## Frequently Asked Questions

### What is the main difference between Aider and Claude Code?

Aider is git-first and model-agnostic - every edit commits automatically with descriptive messages, and you can point it at any LLM provider. Claude Code is runtime-first with subagents, hooks, and workflow orchestration tightly optimized for Anthropic's models. Aider prioritizes clean git history and rollback. Claude Code prioritizes controlled automation and policy-aware delegation.

### Is Aider free to use?

Yes, Aider itself is free and open source. You bring your own API keys from any provider - OpenAI, Anthropic, OpenRouter, or local models. Your cost is whatever the model provider charges per token. There is no Aider subscription or license fee.

### Can I use Claude Code with models other than Claude?

No. Claude Code is tightly coupled to Anthropic's runtime and model ecosystem. You can target different Claude models (Haiku, Sonnet, Opus) within subagent configurations, but you cannot swap in GPT, Gemini, or local models. For provider flexibility, use Aider or other model-agnostic tools.

### Which tool has better cost control?

Both require careful process design. Aider lets you explicitly route prompts to cheaper models for exploration and premium models for final edits - useful if you want to manage costs manually. Claude Code's Pro/Max plans bundle usage with your Anthropic subscription, which simplifies billing but shares limits with Claude itself. Neither tool is inherently cheaper; disciplined prompting beats tool choice for cost efficiency.

### Should I use Aider or Claude Code for a team?

It depends on your governance model. If your team already enforces strict git discipline and wants every AI edit to be a reviewable commit, Aider fits naturally. If you need policy-aware automation with tool-capability boundaries, hook-based quality gates, and teammate-style parallel workflows, Claude Code's subagent system is better suited. Many advanced teams run both - Aider for quick auditable edits, Claude Code for complex orchestration.

### Can Aider run subagents like Claude Code?

No. Aider operates as a single-agent system focused on git-based file editing. It does not have native subagent spawning, tool allowlists, or hook lifecycle events. Claude Code's subagent architecture is a core differentiator for multi-step autonomous tasks where you need different agents with different capabilities running in parallel.

### What is the /architect mode in Aider?

Architect mode is an Aider feature that splits work between a reasoning model and an execution model. The architect model (typically a more capable model like Claude Opus) plans the changes, and a faster model (like Sonnet or GPT-4o) implements them. This pattern can improve quality on complex tasks while keeping costs reasonable. Claude Code achieves similar behavior through explicit subagent delegation with model overrides.

### Which tool is better for beginners?

Aider has a gentler learning curve if you are already comfortable with git and the command line. The single-agent model is easier to reason about. Claude Code's subagent and hook systems add power but also complexity. Start with whichever tool aligns with your existing workflow - git-heavy teams should try Aider first, while teams wanting autonomous multi-step execution may prefer Claude Code.


Claude Code Usage Limits in 2026: The Practical Playbook for Pro and Max Teams
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
Most teams do not lose productivity because of model quality. They lose it because they treat usage limits as a mystery.

In 2026, [Claude Code](/blog/what-is-claude-code-complete-guide-2026) usage management is mostly an operations problem. If you solve routing, guardrails, and workload shaping, your effective throughput jumps without changing models.

If you landed here because Claude Code feels expensive, start with the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison), then compare the plan math against [Claude Code vs Codex](/blog/claude-code-vs-codex-app-2026), [Aider vs Claude Code](/blog/aider-vs-claude-code), and [Gemini CLI](/blog/gemini-cli-guide). Usage limits are only one part of the decision; autonomy, model lock-in, free-tier capacity, and review overhead matter just as much.

## What the Official Docs Make Clear

From [Anthropic](/blog/anthropic-vs-openai-developer-experience) support and pricing docs:

For cost context, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) alongside [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); together they separate sticker price from the operational habits that make agent work expensive.

- Pro and Max usage is shared across Claude and Claude Code.
- Max is currently packaged in 5x and 20x tiers.
- If `ANTHROPIC_API_KEY` is set, Claude Code can authenticate via API key and trigger API billing instead of subscription usage.

That third point is the most common avoidable billing mistake.

## The Real Usage Model

Think in three buckets:

1. Included plan capacity (Pro/Max shared pool).
2. Optional extra usage / pay-as-you-go fallback.
3. Full API-key path with API-rate billing.

If your team does not explicitly choose one per workflow, cost and capacity behavior will look random.

## A Control Plan That Works

### 1) Lock auth mode by environment

Define whether each environment should use:

- Plan-only auth,
- plan + overflow,
- or full API usage.

Then enforce it in shell startup and project setup scripts.

### 2) Use subagent capability boundaries

Anthropic's subagent docs support explicit tool-level scope control.

Use this to protect expensive or risky paths:

- "safe-research" agents: read/search/bash only.
- "implementer" agents: write/edit allowed.
- restricted [MCP](/blog/what-is-mcp) exposure by role.

This reduces unnecessary tool churn and keeps tasks scoped.

### 3) Add hooks for quality gates

Hooks support task lifecycle checks, including TaskCompleted controls.

Practical pattern:

- run lint/typecheck/test in TaskCompleted hooks,
- block completion when checks fail,
- feed back actionable errors.

This prevents repeated expensive repair loops later in the same session.

### 4) Split workload by difficulty lane

- Lane A: simple edits and docs - cheaper/faster model preference.
- Lane B: architecture/refactors - premium model only.
- Lane C: exploratory research - constrained tool profile + strict output format.

Without laneing, teams overuse premium reasoning on low-value edits.

## Signs You Need to Reconfigure, Not Upgrade

1. Usage spikes after short prompts.
2. Frequent context resets with low output quality.
3. Heavy spend in sessions doing mostly search/read operations.
4. Team members report different cost behavior for similar tasks.

If these happen, do not immediately upgrade plans. Fix policy and routing first.

## A Weekly Operations Cadence

Run this every Friday:

1. Check auth routing consistency across developer machines.
2. Review top 10 longest sessions and classify by lane.
3. Audit hook failures and recurring test-gate patterns.
4. Update subagent tool boundaries where misuse appears.
5. Decide if tier changes are justified by real throughput gains.

This process usually beats ad hoc upgrading.

## Example Team Policy (Simple and Effective)

- Default to Pro/Max allocation.
- Enable API overflow only for emergency shipping windows.
- Keep a dedicated "heavy-refactor" profile for premium tasks.
- Require task completion hooks on all production repos.

This keeps performance predictable and limits billing surprises.

## Community Reaction Pattern (Useful, Not Definitive)

Recent community threads show recurring concern around perceived sudden usage burn changes and session efficiency.

Treat this as telemetry inspiration:

- instrument your own usage per workflow lane,
- track productivity outcome, not raw token counts,
- and resolve configuration drift quickly.

## Sources (Docs + Support)

- Anthropic Support: [Using Claude Code with Pro or Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- Anthropic Help Center: [Understanding usage and length limits](https://support.anthropic.com/en/articles/11647753-understanding-usage-and-length-limits)
- Claude Code Docs: [Errors and extra usage](https://code.claude.com/docs/en/errors)
- Anthropic: [Max plan pricing](https://claude.com/pricing/max)
- Anthropic Docs: [Claude Code getting started](https://code.claude.com/docs/en/getting-started)
- Anthropic Docs: [Subagents](https://code.claude.com/docs/en/sub-agents)
- Anthropic Docs: [Hooks](https://code.claude.com/docs/en/hooks)
- Community signal: [r/ClaudeCode usage thread](https://www.reddit.com/r/ClaudeCode/comments/1s2kdl9/claude_suddenly_eating_up_your_usage_here_is_what/)

## Frequently Asked Questions

### What are the Claude Code usage limits in 2026?

Claude Code usage limits depend on your Anthropic subscription tier. Pro ($20/month) provides a shared usage pool across Claude and Claude Code with lower capacity. Max plans come in 5x ($100/month) and 20x ($200/month) tiers with significantly higher limits. Usage is measured in tokens consumed, not sessions or prompts. If you set `ANTHROPIC_API_KEY`, Claude Code switches to API billing which is pay-per-use and separate from your subscription.

### How do I avoid unexpected Claude Code billing?

The most common billing mistake is having `ANTHROPIC_API_KEY` set in your environment. When this key is present, Claude Code authenticates via API and triggers API billing instead of your subscription usage. To avoid surprises, explicitly lock your auth mode per environment: use plan-only auth for normal work, enable API overflow only for critical shipping windows, and audit your shell startup scripts for stray API keys.

### Why is Claude Code using so much of my quota?

Heavy quota burn usually comes from poor workload routing, not model quality issues. Check for: (1) context resets with low output quality causing repeated work, (2) sessions doing mostly read/search operations that could use cheaper models, (3) missing quality gates that let failing code trigger expensive repair loops. Fix routing and add hooks before considering a plan upgrade.

### What is the difference between Claude Code Pro and Max plans?

Pro ($20/month) shares a modest usage pool between Claude chat and Claude Code - suitable for lighter usage. Max 5x ($100/month) provides 5x the usage capacity of Pro, while Max 20x ($200/month) provides 20x capacity. Max plans support longer autonomous sessions, more parallel [sub-agents](/blog/claude-code-sub-agents), and heavy daily use. Teams doing serious development usually need Max 5x minimum.

### How do I reduce Claude Code token usage without losing productivity?

Use three strategies: (1) Split workloads by difficulty lane - simple edits use cheaper models, architecture work uses premium. (2) Add TaskCompleted hooks that run lint/typecheck/test before marking tasks done, preventing expensive repair loops. (3) Scope sub-agents by capability - research agents get read-only access, implementers get write access. This reduces tool churn and keeps sessions focused.

### Can I use my own API key with Claude Code?

Yes. If you set `ANTHROPIC_API_KEY` in your environment, Claude Code authenticates via API rather than your subscription. This triggers pay-per-use API billing at standard Anthropic API rates. This is useful for teams that prefer usage-based billing or need to exceed subscription limits, but watch for accidental API key exposure that causes unexpected charges.

### How do I track Claude Code usage across my team?

Run a weekly operations cadence: (1) Check auth routing consistency across developer machines. (2) Review the top 10 longest sessions and classify by workload lane. (3) Audit hook failures and recurring test-gate patterns. (4) Update sub-agent tool boundaries where misuse appears. Instrument your own usage per workflow lane and track productivity outcomes, not just raw token counts.

### Should I upgrade my Claude Code plan if I keep hitting limits?

Not immediately. First fix policy and routing: check for auth mode inconsistencies, add quality gate hooks, split workloads by difficulty lane, and scope sub-agent capabilities. These changes often unlock 2-3x effective throughput without plan changes. Only upgrade tiers when real productivity gains justify the cost after you have optimized routing and guardrails.


Claude Code vs Codex App in 2026: Local Agent Pairing vs Cloud Agent Orchestration
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
If you are evaluating [coding agents](/blog/what-is-an-ai-coding-agent-2026) in 2026, the most important decision is not model quality alone. It is execution model.

- [Claude Code](/blog/what-is-claude-code-complete-guide-2026) is strongest when you want tight local loop execution with project-native constraints and explicit tool control.
- [Codex](/blog/openai-codex-guide) app is strongest when you want to orchestrate multiple long-running agents in parallel, often in cloud environments, with desktop supervision.

This guide focuses on what changed recently and what matters in production.

## What Changed Recently

[OpenAI](/blog/openai-vs-anthropic-2026) shipped a major Codex desktop push in Q1 2026:

For the larger agent workflow map, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) and [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they give the architecture and implementation context this piece assumes.

- Codex app launched on macOS (February 2, 2026) and then Windows support was added (March 4, 2026).
- OpenAI positioned the app as a "command center" for multi-agent workflows with built-in worktree support and isolated copies per agent.
- GPT-5.3-Codex launched on February 5, 2026 as OpenAI's most capable agentic coding model, with OpenAI stating it is 25% faster for Codex users.

Anthropic doubled down on operational controls for Claude Code in docs and support guidance:

- Subagents with explicit tool allowlists and denylists.
- Hook events for workflow gating, including TaskCompleted checks.
- Clear plan behavior around Pro and Max usage limits and API-key vs subscription routing.

These are not minor feature deltas. They change team workflow design.

## Architecture Difference That Actually Matters

### Claude Code: Conversation-centric local runtime

Claude Code is optimized for direct local collaboration in your terminal and project context. The major leverage points in 2026 are:

1. Subagents with explicit capability control.
2. Hooks for policy and automation at key lifecycle events.
3. Memory/instruction shaping via project rules and settings.

This makes Claude Code feel like a programmable local teammate with high controllability.

### Codex App: Agent operations console

Codex app is designed around supervising concurrent agents over long tasks. OpenAI's framing is explicit: the bottleneck is no longer what agents can do, it is how humans direct and supervise many agents.

The app model favors:

1. Multiple concurrent agent threads.
2. Worktree isolation for parallel branch-safe work.
3. Unified state across app, CLI, IDE extension, and web.

This is better if your bottleneck is coordination throughput, not single-session depth.

## Security and Internet Access Model

### Codex cloud internet controls

OpenAI documents that in cloud tasks:

- Agent internet is blocked by default in the agent phase.
- Setup scripts still run with internet access for dependency installation.
- Internet can be enabled per environment with domain/method controls.

OpenAI also explicitly documents prompt-injection and exfiltration risks when internet is enabled. This is a strong signal that "agent networking" is now a first-class production security concern.

### Claude Code local and tool-scope controls

Anthropic's operational controls are more tool-policy centric inside the session model:

- Subagents inherit tools by default, including MCP tools.
- Teams can explicitly constrain tool access (`tools`, `disallowedTools`) per subagent profile.
- Hook-based checks can block task completion when quality gates fail.

Net: Codex cloud docs emphasize network boundary governance. Claude Code docs emphasize tool and execution governance inside the coding session.

## Pricing and Access Reality

### Claude side

Anthropic's Max plan page currently presents:

- Max 5x: $100/month
- Max 20x: $200/month

Support docs clarify that usage limits are shared across Claude and Claude Code. They also highlight an important operational trap: if `ANTHROPIC_API_KEY` is set, Claude Code can route to API billing instead of subscription usage.

### Codex side

OpenAI documentation currently positions Codex access as included in Plus, Pro, Business, Edu, or Enterprise plans (with admin setup caveats for some enterprise workspaces). Product posts also documented temporary broader inclusion and higher limits during app rollout periods.

The practical implication for teams: cost predictability can diverge from list pricing based on authentication path, plan tier, and how much work is run cloud-side vs local.

## Where Each Tool Wins Right Now

### Pick Claude Code when

- You want strict, explicit local workflow control.
- You need rich hook automation and subagent permission shaping.
- Your team already has mature terminal and repo conventions.
- You optimize for deterministic coding process over visual orchestration.

### Pick Codex app when

- You want to supervise many tasks in parallel from a single UI.
- You rely on long-running delegated workflows.
- You value app/IDE/CLI/web continuity for distributed teams.
- You want cloud-task style delegation as a default mode.

## Team Pattern That Works in Practice

Most high-performing teams do not choose one tool globally.

They split by workflow type:

- Local implementation, focused refactor loops, and policy-heavy code changes: Claude Code.
- Parallel background delegation, multi-thread work planning, and broad research/execution batches: Codex app + cloud tasks.

If you are running a serious AI coding stack in 2026, the best architecture is often dual-track.

## Common Failure Modes to Avoid

1. Treating model quality as the only decision variable.
Execution model and control surface will impact throughput more than benchmark deltas for most teams.

2. Ignoring auth and billing routing.
Plan entitlements and API-key behavior can change actual cost curves quickly.

3. Enabling internet access without domain/method guardrails.
Both security posture and reproducibility degrade fast without policy.

4. Running parallel agents without branch/worktree discipline.
Agent throughput gains disappear if merge conflicts become your new bottleneck.

## Sources (Docs + Announcements)

- OpenAI: [Introducing the Codex app](https://openai.com/index/introducing-the-codex-app/)
- OpenAI: [Introducing GPT-5.3-Codex](https://openai.com/index/introducing-gpt-5-3-codex/)
- OpenAI: [Introducing upgrades to Codex](https://openai.com/index/introducing-upgrades-to-codex/)
- OpenAI: [Codex is now generally available](https://openai.com/index/codex-now-generally-available/)
- OpenAI Developers: [Codex cloud docs](https://developers.openai.com/codex/cloud)
- OpenAI Developers: [Agent internet access](https://developers.openai.com/codex/cloud/internet-access)
- OpenAI Developers: [API changelog](https://developers.openai.com/api/docs/changelog)
- Anthropic Claude: [Max plan pricing](https://claude.com/pricing/max)
- Anthropic Support: [Using Claude Code with Pro/Max](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- Anthropic Docs: [Claude Code getting started](https://code.claude.com/docs/en/getting-started)
- Anthropic Docs: [Subagents](https://code.claude.com/docs/en/sub-agents)
- Anthropic Docs: [Hooks](https://code.claude.com/docs/en/hooks)

## Frequently Asked Questions

### What is the main difference between Claude Code and Codex app?

Claude Code is a local terminal agent optimized for tight feedback loops in your project directory with explicit tool control via subagents and hooks. Codex app is a desktop application designed for supervising multiple long-running agents in parallel, with cloud execution capabilities and unified state across app, CLI, IDE extension, and web interfaces.

### Which is better for solo developers?

For solo developers, Claude Code typically fits better because it emphasizes direct local collaboration in your terminal with programmable control over agent behavior. The subagent and hook systems let you shape workflows to match your conventions without managing a separate orchestration layer. Codex app's strengths in multi-agent coordination are more valuable for teams.

### Can I use both Claude Code and Codex app together?

Yes, and many high-performing teams do exactly this. The recommended pattern is using Claude Code for local implementation, focused refactor loops, and policy-heavy code changes, while using Codex app for parallel background delegation, multi-thread work planning, and broad research or execution batches. The tools address different workflow shapes rather than competing directly.

### How does pricing compare between Claude Code and Codex?

Claude Code requires an Anthropic Max plan at $100/month (5x limits) or $200/month (20x limits), with usage shared across Claude and Claude Code. Codex access is included with OpenAI Plus, Pro, Business, Edu, or Enterprise plans. Watch for the billing routing trap: if `ANTHROPIC_API_KEY` is set, Claude Code can route to API billing instead of your subscription.

### Is internet access handled differently?

Yes, significantly. Codex cloud tasks block agent internet by default during the agent phase (though setup scripts run with internet for dependency installation). Internet can be enabled per environment with domain and method controls. Claude Code's operational controls focus more on tool and execution governance inside the session rather than network boundary governance.

### Which tool is better for parallel agent work?

Codex app is explicitly designed for supervising concurrent agents over long tasks. It includes built-in worktree support with isolated copies per agent, making it well-suited for parallel branch-safe work. Claude Code can run subagents in parallel, but the orchestration is conversation-centric rather than having a dedicated visual operations console.

### What are the main security considerations?

For Codex, the primary concern is internet access governance - OpenAI explicitly documents prompt-injection and exfiltration risks when internet is enabled. For Claude Code, security focuses on tool-policy controls: subagents inherit tools by default (including MCP tools), so teams should explicitly constrain tool access via `tools` and `disallowedTools` configuration per subagent profile.

### Which should I choose if I already use the terminal heavily?

If you have mature terminal and repo conventions, Claude Code is the natural fit. Its local runtime model, explicit hook automation, and subagent permission shaping work well with existing CLI workflows. Codex app provides more value when you want visual orchestration and cross-platform state continuity (app, IDE, CLI, web) over pure terminal operation.


Copilot Pro+ Premium Requests Explained in 2026: What Teams Miss in Pricing Comparisons
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
Most Copilot [pricing](/blog/ai-coding-tools-pricing-2026) confusion comes from one mistake: comparing monthly plan price without modeling premium request burn.

In 2026, [Copilot](/blog/github-copilot-coding-agent-cli-2026) documentation is explicit about this, and teams should treat request budgeting as part of engineering operations.

## Current Plan Signals from Official Docs

GitHub docs currently describe:

For cost context, read [GitHub Copilot in 2026: Still Worth It for TypeScript Developers?](/blog/github-copilot-guide) alongside [AI Coding Tools Pricing in Q2 2026: What Actually Changed and Where Costs Surprise Teams](/blog/ai-coding-tools-pricing-q2-2026); together they separate sticker price from the operational habits that make agent work expensive.

- Pro: $10/month
- Pro+: $39/month
- Business: $19/seat/month
- Enterprise: $39/seat/month

The same plan docs also show premium request pools by tier and a paid overage option. This matters more than headline monthly price for heavy users.

## Premium Requests Are the Real Cost Lever

GitHub's plan table currently documents:

- Free: 50 premium requests/month
- Pro: 300/month
- Pro+: 1500/month
- Business: 300/user/month
- Enterprise: 1000/user/month
- Additional premium requests purchasable at listed per-request rates

If your workflow leans on premium models and agent-like flows, this can dominate total cost behavior.

## Model Access Is Not the Same as Model Economics

Plan docs list broad model availability, including recent frontier options. But access alone does not tell you the effective cost per completed task.

Teams should track:

1. requests consumed per merged PR,
2. request-heavy tasks by workflow stage,
3. whether premium models are being used on low-complexity tasks.

Without this, many teams over-upgrade from Pro to Pro+ and still waste request budget.

## Practical Cost Controls That Work

### 1) Split work by request value

Use premium requests for:

- large refactors,
- tricky bug hunts,
- architecture-sensitive code generation.

Use default/cheaper paths for:

- boilerplate,
- small edits,
- repetitive transformations.

### 2) Enforce prompt quality standards

Better constraints reduce retries, and retries are hidden request multipliers.

### 3) Monitor request burn by engineer role

Senior staff doing architecture and review tasks can justify higher request pools. Many occasional users cannot.

### 4) Re-tier monthly

Treat Pro+ as a utilization decision, not a default team standard.

## Common Team Failure Modes

1. Buying Pro+ for everyone immediately.
2. Ignoring request telemetry until end-of-month overage.
3. Using premium models for low-risk formatting tasks.
4. Comparing Copilot price to other tools without normalizing for workflow type.

## Selection Guidance

### Copilot Pro is usually enough when

- most usage is inline suggestions and moderate chat support,
- advanced model prompts are occasional,
- team has strong code review discipline.

### Copilot Pro+ makes sense when

- premium models are core to daily execution,
- request-heavy agent flows are routine,
- you can prove throughput gains vs extra spend.

## Frequently Asked Questions

### What is the difference between Copilot Pro and Pro+?

Copilot Pro [costs](/blog/ai-coding-tools-pricing-comparison) $10/month and includes 300 premium requests. Pro+ costs $39/month and includes 1500 premium requests. Both have access to the same models, but Pro+ gives you 5x the premium request budget. The price difference only makes sense if you regularly exhaust your Pro allocation on premium model features like agent flows, complex refactors, or multi-file edits.

### What counts as a premium request in GitHub Copilot?

Premium requests are consumed when you use advanced features that rely on frontier models - agent mode conversations, complex multi-turn chat sessions, large context window operations, and certain code generation tasks. Standard inline completions and basic chat typically use the default model tier and do not count against your premium budget.

### How do I check my premium request usage?

GitHub provides request telemetry in your Copilot settings. You can see your current month's usage, remaining allocation, and historical consumption patterns. Teams on Business or Enterprise plans get per-seat breakdowns. Monitor this weekly rather than waiting for end-of-month surprises.

### Can I buy additional premium requests if I run out?

Yes. GitHub offers paid overage at published per-request rates. However, if you consistently need overages, you are better off upgrading to the next tier or optimizing your usage patterns. Overage pricing is designed for occasional spikes, not sustained heavy use.

### Is Copilot Pro+ worth it for solo developers?

It depends on your workflow. If you primarily use inline completions and occasional chat, Pro's 300 requests is plenty. If you rely heavily on agent-like flows, use premium models for architecture decisions, or do multiple large refactors per week, Pro+ pays for itself in productivity. Track your actual request burn for a month on Pro before upgrading.

### How does Copilot Business compare to Pro+ for teams?

Business ($19/seat/month) includes 300 premium requests per user plus admin controls, usage analytics, and policy management. Enterprise ($39/seat/month) includes 1000 requests per user plus additional security features. For small teams where everyone needs high request volumes, individual Pro+ subscriptions might cost less than Business - but you lose centralized management.

### What is the best strategy to avoid wasting premium requests?

Three rules: (1) Use premium models only for high-value tasks like architecture, complex debugging, and large refactors - not for boilerplate or formatting. (2) Write better prompts to reduce retries - every failed attempt burns requests. (3) Split your team by usage profile - heavy users on Pro+, occasional users on Pro.

### Do premium requests roll over to the next month?

No. Unused premium requests expire at the end of each billing cycle. There is no accumulation or banking. This is why right-sizing your tier matters more than buying the biggest plan available.

---

## Sources

- GitHub Docs: [Plans for Copilot](https://docs.github.com/en/copilot/get-started/plans)
- GitHub: [Copilot plans and pricing](https://github.com/features/copilot/plans)


OpenAI Codex Cloud Security Playbook 2026: Internet Access, Prompt Injection, and Safe Defaults
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
Codex cloud can be a major force multiplier, but internet-enabled agent execution changes your threat model.

OpenAI's Codex docs now provide enough detail to run cloud tasks safely if you treat security policy as part of everyday developer workflow.

## Security Baseline from Official Docs

OpenAI's Codex internet-access docs state:

For the security frame around this, see [OpenAI Codex: Cloud AI Coding With GPT-5.3](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); both focus on the places where agent autonomy needs explicit boundaries.

- Internet is blocked by default during the agent phase.
- Setup scripts still have internet access for dependency installation.
- Internet access can be configured per environment.

This is a strong default posture, but it is only the starting point.

## Documented Risks You Should Treat as Real

OpenAI explicitly calls out:

1. prompt injection from untrusted content,
2. exfiltration of code or secrets,
3. downloading malicious or vulnerable dependencies,
4. license risk from imported external content.

These are not theoretical. If your agent can fetch and execute with weak constraints, they become routine operational risk.

## Hardening Pattern That Works

### 1) Keep internet off by default

Only enable internet on environments that truly require remote fetches.

### 2) Use strict domain allowlists

Prefer specific domains over unrestricted access. Start narrow and expand only when task failures prove necessity.

### 3) Restrict HTTP methods

OpenAI docs indicate you can limit methods. Restrict to `GET`, `HEAD`, and `OPTIONS` when possible.

This blocks many exfiltration patterns that rely on write-capable outbound requests.

### 4) Review work logs and outputs as policy

OpenAI recommends reviewing output and logs. Make this mandatory for PRs created from cloud tasks.

### 5) Separate environments by trust level

Use separate Codex environments for:

- high-trust internal repos,
- medium-trust open-source contribution work,
- low-trust external issue triage.

Do not share permissive network policy across all environments.

## Prompt Injection Example and Why It Matters

OpenAI docs provide an example where untrusted instructions could induce data leakage via outbound requests.

Practical implication:

- Treat all remote issue text, docs, and READMEs as untrusted input.
- Do not grant broad outbound internet + unrestricted methods in default environments.

## Operational Guardrails for Teams

1. Add environment templates with approved domains.
2. Require explicit justification for "internet on" environments.
3. Add PR checklist items for cloud-task trace review.
4. Rotate and scope credentials used in setup scripts.
5. Track incidents and near-misses as part of engineering retros.

## How This Relates to Codex Product Direction

OpenAI product updates emphasize parallel [multi-agent workflows](/blog/building-multi-agent-workflows-claude-code) and long-running delegation. That increases productivity and coordination throughput.

It also means small policy mistakes can scale faster. A weak default replicated across many tasks is a multiplier in the wrong direction.

Security maturity is now a competitive advantage for teams using [coding agents](/blog/what-is-an-ai-coding-agent-2026) at scale.

## Sources

- OpenAI Developers: [Codex cloud](https://developers.openai.com/codex/cloud)
- OpenAI Developers: [Agent internet access](https://developers.openai.com/codex/cloud/internet-access)
- OpenAI: [Introducing the Codex app](https://openai.com/index/introducing-the-codex-app/)
- OpenAI: [Introducing upgrades to Codex](https://openai.com/index/introducing-upgrades-to-codex/)
- OpenAI: [Codex is now generally available](https://openai.com/index/codex-now-generally-available/)
- OpenAI Developers: [API changelog](https://developers.openai.com/api/docs/changelog)


What Hacker News Gets Right About AI Coding Agents in 2026
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
If you want to know where AI coding is going, Hacker News is still a useful signal. Not because every comment is right. Most are not. But because the same arguments keep resurfacing, and repeated arguments usually point to real pressure in the market.

Over the last few months, Hacker News threads around [Skills Officially Comes to Codex](https://news.ycombinator.com/item?id=46334424), [Agent Skills](https://news.ycombinator.com/item?id=46871173), the hiring debate around [hands-on agentic programming](https://news.ycombinator.com/item?id=47420814), and the broader Claude Code vs. Codex conversation have converged on the same core themes.

Those themes also show up outside HN. Axios framed 2026 as AI's ["show me the money" year](https://www.axios.com/2026/01/01/ai-2026-money-openai-google-anthropic-agents). Recent research on agent-generated pull requests found that no single coding agent dominates every task category, and that tool quality depends heavily on task shape rather than abstract benchmark supremacy. That is exactly the kind of nuance HN has been groping toward in public.

Here is what Hacker News gets right about [AI coding agents](/blog/what-is-an-ai-coding-agent-2026) in 2026.

## 1. The Real Product Is the Workflow, Not the Model

Most surface-level comparisons still ask the wrong question. They ask whether [Claude Code](/blog/what-is-claude-code-complete-guide-2026) or Codex or Cursor has the "best" model. Hacker News has mostly moved past that.

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

The serious conversations are now about workflow fit:

- Does the tool preserve context over long sessions?
- Can it inspect a real codebase without wasting half the session rediscovering structure?
- Can it compose with shell commands, [browser automation](/blog/claude-code-chrome-automation), git, and external systems?
- Can a developer supervise it without feeling like they are fighting the harness?

That is the right frame.

The model matters, obviously. But once you cross a threshold of acceptable reasoning quality, the winning product is the one that fits real development loops. That means terminal access, filesystem access, durable project context, and useful failure recovery. It also means the tool should behave well under repeated use, not just in a benchmark video.

This is why terminal-native agents keep pulling attention. They sit closer to the actual work. Developers already use the terminal for builds, tests, local servers, migrations, package management, and deployment scripts. Putting the agent there reduces translation cost.

This is also why the current category feels fragmented. Developers are not choosing one universal tool. They are choosing one tool for exploration, another for iterative editor work, another for long-running agent sessions, and sometimes a fourth for browser or infra-heavy tasks.

That fragmentation is not confusion. It is the market discovering that "AI coding" is not one job.

## 2. Skills Are Becoming More Important Than Raw Prompting

Two separate HN threads about skills landed on the same point: project-specific reusable instructions are becoming more valuable than one-off prompting.

That tracks with what serious teams are already learning. The bottleneck is not "how do I ask the model nicely." The bottleneck is encoding your local rules, repo conventions, tool usage patterns, and operational expectations in a form the agent can repeatedly reuse.

Skills solve several problems at once:

- They compress context into reusable guidance.
- They make tool usage more deterministic.
- They reduce the need to restate house rules every session.
- They let teams standardize agent behavior without custom wrappers for every task.

This is also why the industry keeps arguing about file names like `AGENTS.md`, `CLAUDE.md`, and other tool-specific conventions. The naming war itself is not important. The underlying need is important. Teams want a stable place to store agent-operating knowledge close to the code.

If you are still relying on giant custom prompts pasted into every session, you are using 2025 tactics in a 2026 environment.

The better pattern is:

1. Put project rules close to the repo.
2. Encode repeatable workflows as skills or equivalent local instructions.
3. Keep prompts short and task-specific.

That is a more scalable operating model than heroic prompting.

## 3. Orchestration Matters More Than Autonomy

This is probably the most important thing HN has gotten right.

The frontier demos still focus on autonomy. Give the agent a big task, walk away, come back later. That makes for good screenshots and dramatic launch copy. But the developers actually getting value from these systems are usually doing something more boring and more effective: orchestrating multiple bounded workflows.

That means:

- one agent researching docs
- one agent modifying a specific subsystem
- one agent handling tests or verification
- one agent synthesizing the result

The supervisor is still human most of the time.

This is not a weakness. It is the current best practice.

Recent writing and research keep converging on this point. The most credible path to production value is not full autonomy. It is coherent orchestration with clear task boundaries, explicit handoffs, and deterministic checks around the model.

That is also why [multi-agent systems](/blog/multi-agent-systems) are becoming more practical. They are not useful because "more agents" sounds futuristic. They are useful because software work already contains parallelizable subproblems.

Hacker News is right to be skeptical of grand claims about one-shot autonomous software production. But it is equally wrong when it dismisses the entire category because the most theatrical claims are overstated.

The right frame is simpler:

- autonomy is overrated as a branding term
- orchestration is underrated as a production pattern

## 4. Verification Is the Real Bottleneck

HN keeps circling back to the same complaint: the agent can produce code quickly, but someone still has to decide whether the output is trustworthy.

That complaint is not resistance. It is diagnosis.

The core bottleneck in 2026 is no longer code generation speed. It is verification capacity.

You can see that in current research as well. One study on coding-agent pull requests found materially different performance by task type rather than a single universal winner. Another large-scale study of agent-generated pull requests highlighted that the shape and review characteristics of agent work differ from human-written work in ways teams need to account for.

That matches lived experience:

- Simple scaffolding gets faster.
- First drafts get faster.
- Boilerplate gets much faster.
- Final trust still costs time.

The more mature teams are responding accordingly. They are investing in:

- stronger repo conventions
- better linting and type systems
- more deterministic tests
- clearer task decomposition
- narrower agent scopes

That is not anti-AI. That is how you absorb more AI-generated output without drowning in review debt.

If an organization says "agents don't work for us," the real translation is often "our verification pipeline cannot absorb the volume or variability of generated changes."

That is a workflow problem, not just a model problem.

## 5. The Market Cares More About Payoff Than Spectacle Now

Axios had the right macro framing: 2026 is the year AI has to show financial payoff, not just qualitative magic.

That shift matters for developers too.

The discourse is moving from:

- "look what the model can do"

to:

- "what part of the engineering workflow does this reliably improve"

That change is healthy.

A lot of noisy AI coding discourse still assumes the category is about replacing developers or automating software end to end. The more grounded version is narrower and more useful:

- compress setup time
- accelerate known workflows
- reduce context-switching
- parallelize bounded work
- make documentation and migration tasks less painful

The tools that win the next phase will be the ones that produce reliable economic leverage inside those constraints.

That is also why HN discussions now spend so much time on pricing, session limits, context behavior, harness design, and workflow friction. Those are not side issues. Those are the product.

## What Developers Should Do With This Signal

The practical takeaway is not "pick a winner" and stop thinking.

It is this:

### Treat agents like workflow infrastructure

Do not adopt them as entertainment products. Adopt them the same way you adopt CI, observability, or a database migration tool: with clear expectations, boundaries, and operating rules.

### Standardize project context

Use repo-local instructions, skills, and stable agent-facing documentation. The teams that externalize their operating knowledge will outperform the teams that rely on memory and ad hoc prompting.

### Optimize for reviewability

The highest-leverage improvement is often not a better model. It is making changes easier to verify. Smaller diffs, stronger types, explicit tests, and isolated scopes matter more than people want to admit.

### Learn orchestration, not just prompting

The durable skill is not writing clever prompts. It is decomposing work, deciding what can run in parallel, and designing good human checkpoints.

### Stop expecting one tool to do everything

The market is still sorting itself out. Use the best tool for the job instead of forcing one harness to be your editor, researcher, browser, release manager, and infra operator all at once.

## The Bottom Line

Hacker News is noisy, but the signal is getting sharper.

The important story in 2026 is not that coding agents exist. That story is old. The important story is that the conversation has matured. Developers are arguing less about whether these tools are "real" and more about how to make them economically useful, operationally trustworthy, and structurally repeatable.

That is progress.

The winning mental model is no longer "AI writes code for me."

It is:

AI agents are a new layer in the software production stack. They need context, supervision, reusable operating rules, and deterministic systems around them. Teams that understand that will get real leverage. Teams that keep treating agents like magic demos will keep getting inconsistent results.

That is what Hacker News is actually saying, underneath all the shouting.


Why Skills Beat Prompts for Coding Agents in 2026
Developers Digest — Sat, 18 Apr 2026 00:00:00 GMT
The most useful coding-agent shift in 2026 is not a new model release. It is the industry's slow realization that giant prompts do not scale.

Hacker News has been circling this point for months. The threads around [Skills Officially Comes to Codex](https://news.ycombinator.com/item?id=46334424), [OpenAI quietly adopting skills](https://news.ycombinator.com/item?id=46250332), and the broader control-layer discussion in [Why AI coding agents feel powerful at first, then become harder to control](https://news.ycombinator.com/item?id=46834002) all point in the same direction:

Prompting is not disappearing, but it is being demoted.

The better pattern is a stack:

- repo-local rules for project constraints
- skills for reusable methodology
- [sub-agents](/blog/claude-code-sub-agents) for bounded responsibility
- MCP or CLI tools for observation and action
- hooks, tests, and review steps for guarantees

That stack is much closer to how real software work already behaves.

## Prompts Worked Fine Until They Did Not

At small scale, prompting feels magical.

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

You write a careful request. The agent does something impressive. You refine it a little. Everything feels fast.

Then the codebase grows.

Now the same session has to remember:

- file naming conventions
- deployment rules
- testing expectations
- security constraints
- dependency preferences
- product-specific edge cases
- internal architectural decisions

That is when prompt-only workflows start to degrade.

The prompt gets longer. The same instructions get repeated every day. Constraints leak into task wording. One session behaves well, the next ignores the exact same preference. The system still looks capable, but it becomes inconsistent.

That inconsistency is what developers are actually complaining about when they say [coding agents](/blog/what-is-an-ai-coding-agent-2026) "feel harder to control" over time.

## Skills Solve a Different Problem Than MCP

One reason this conversation gets muddled is that people keep comparing skills and MCP as if they are substitutes.

They are not.

MCP is mostly about connection:

- expose tools
- pass data
- standardize integration
- centralize auth and observability

Skills are mostly about operating knowledge:

- when to use a tool
- how to approach a recurring task
- what sequence of steps works best
- which local conventions the agent should respect

This is why the strongest HN comments on skills keep making the same point: a markdown-based skill can tell the agent how to properly use existing tools, including MCP tools, without forcing that behavior into the main prompt every time.

That is a big deal.

A good skill is not just a stored prompt. It is reusable method.

## Why Skills Win in Practice

Skills are becoming a standard because they match the shape of repeated developer work.

Most useful coding work is not unique. It rhymes.

You keep doing variations of the same things:

- add a feature with tests
- debug a deployment
- triage a flaky failure
- review a security-sensitive diff
- wire a new API integration
- migrate a route or schema

Each of those tasks benefits from a preferred approach. Not just a desired output. An approach.

That is where skills outperform prompts.

### 1. Skills compress repeated context

Instead of restating the same instructions in every session, you keep the repeatable parts in a reusable unit.

That makes prompts shorter and easier to reason about.

### 2. Skills compose better

One task might need a deployment-debugging skill plus a documentation-checking skill plus a repo-specific testing skill.

That is a more scalable model than trying to encode every possible combination into one giant system prompt.

### 3. Skills reduce token waste

The model does not need the full body of every workflow instruction at all times. It only needs to load the relevant one when the task calls for it.

That is one reason the "skills as lazy-loaded markdown" model keeps resonating with power users.

### 4. Skills are editable by normal engineers

You do not need a separate prompt-engineering platform or a complex orchestration product to start. A markdown file in the repo is often enough.

That matters. The winning pattern in developer tooling is usually the one that ordinary teams can author and maintain without ceremony.

## The Real Control Stack

The most useful framing I have seen recently is that agent features are not random bells and whistles. They are control layers.

Very roughly:

- rules constrain decisions
- commands trigger execution
- skills encode repeatable methodology
- sub-agents limit scope and ownership
- MCP enables tool access and observation
- hooks and checks enforce guarantees

When teams mix these layers up, things get messy.

Examples:

- using prompts to encode durable repo policy
- using MCP as a substitute for methodology
- using hooks to compensate for poor task decomposition
- using one generalist agent where two bounded specialists would be safer

That is why some teams feel like coding agents are chaotic while others are getting strong results from the same underlying models.

The better teams are not just "prompting better." They are building a better control stack.

## Where MCP Still Wins

This is not an anti-MCP argument.

MCP remains the right abstraction when the problem is:

- authenticated tool access
- structured interaction with external systems
- remote capability exposure
- centralized auditability

If your agent needs to talk to GitHub, Linear, a database, a browser harness, or a deployment system, MCP is often the right connective tissue.

But MCP does not automatically tell the agent how to behave well with those tools.

That is why the sharpest recent HN critiques of "MCP everywhere" are also useful. Developers are noticing that connecting tools is not the same as teaching good operational judgment.

The connector layer is necessary. It is not sufficient.

## What This Means for Teams

If you are using coding agents seriously, the practical next step is not "write a better master prompt."

It is:

### 1. Move durable instructions out of task prompts

Project rules, coding conventions, and repeated operational workflows should live in repo-local files, not in copy-pasted prompts.

### 2. Encode common tasks as skills

Start with the boring, high-frequency work:

- fix CI
- debug deploys
- add tests
- review security-sensitive changes
- handle migrations

Those are the areas where methodology matters most.

### 3. Separate tool access from method

Use MCP or CLI tooling for capability. Use skills for approach. Do not try to jam both concerns into one layer.

### 4. Use sub-agents to bound responsibility

The point of sub-agents is not novelty. It is blast-radius control.

If one agent is researching docs and another is patching infra config, that is often safer than one giant session doing both with one giant context pile.

### 5. Keep human review focused on trust, not transcription

The goal is not to eliminate oversight. It is to move humans up the stack so they review intent, risk, and correctness instead of micromanaging every keystroke.

## The Bottom Line

The prompt era is not over, but prompt maximalism is.

The emerging best practice is to treat coding agents less like chatbots and more like systems. Systems need structure. They need reusable knowledge. They need separation of concerns. They need bounded scopes and deterministic checks.

That is why skills are becoming more important.

Not because they are fashionable. Because they solve a real scaling problem in day-to-day agent use.

In 2026, the teams getting the most leverage from coding agents are not the teams writing the cleverest prompts.

They are the teams building the clearest control stack around the model.


AI Coding Tools Pricing Comparison: What You Actually Pay in 2026
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
Pricing pages lie by omission. Every AI coding tool has a [pricing](/blog/ai-coding-tools-pricing-2026) page that shows you tiers and monthly costs. None of them show you what happens when you actually use the tool for eight hours a day. The real cost of an AI coding tool is not the subscription price. It is the subscription price plus the model access you actually get, plus the usage ceiling you hit, plus the cost of switching when you outgrow the tier.

This is the analysis that pricing pages do not give you. What each tool actually costs for different developer profiles, where the hidden limits live, and how to choose based on how you actually work. Side-by-side cost figures across the major API providers also live on our [AI API pricing comparator](/pricing) if you want to skip ahead to the numbers.

## Official Pricing Sources

Use this page as the analysis layer, then verify current plan details against the official sources before buying or rolling a tool out to a team.

| Tool | Official source |
|------|-----------------|
| Claude Code | [Anthropic pricing](https://www.anthropic.com/pricing) and [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code) |
| Cursor | [Cursor pricing](https://cursor.com/pricing) and [Cursor docs](https://docs.cursor.com) |
| GitHub Copilot | [Copilot plans](https://github.com/features/copilot/plans) and [Copilot billing docs](https://docs.github.com/en/copilot/about-github-copilot/subscription-plans-for-github-copilot) |
| Windsurf | [Windsurf pricing](https://windsurf.com/pricing) |
| OpenAI Codex | [Using Codex with your ChatGPT plan](https://help.openai.com/en/articles/11369540-using-codex-with-your-chatgpt-plan) and [Codex rate card](https://help.openai.com/en/articles/20001106-codex-rate-card) |
| Augment | [Augment pricing](https://www.augmentcode.com/pricing) |
| Gemini CLI | [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli) and [Google AI pricing](https://ai.google.dev/pricing) |
| Zed | [Zed pricing](https://zed.dev/pricing) |

## The Full Pricing Landscape

Here is every major AI coding tool's pricing as of May 2026, including details that pricing pages bury in footnotes.

### Claude Code (Anthropic)

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Pro | $20 | Sonnet 4.6 | Moderate limits, throttled during peak |
| Max 5x | $100 | Opus 4.6 + Sonnet 4.6 | 5x Pro usage, Opus access |
| Max 20x | $200 | Opus 4.6 + Sonnet 4.6 | 20x Pro usage, effectively unlimited |
| Enterprise (via API) | Usage-based | All models | $3/$15 per M input/output tokens (Sonnet/Opus) |

**What the pricing page does not tell you:** The $20 Pro tier gives you access to [Claude Code](/blog/what-is-claude-code-complete-guide-2026) with Sonnet, which is genuinely capable for most tasks. But heavy users will hit rate limits during peak hours. The $100 tier is where Claude Code becomes a different tool entirely because Opus-class reasoning on complex refactors, architectural decisions, and multi-file changes produces noticeably better results.

The $200 tier is for developers who run Claude Code as their primary coding environment for 6 or more hours daily. At API rates, the same usage would cost thousands per month. One developer publicly documented 10 billion tokens over 8 months on the $100 tier, which would have been roughly $15,000 at API pricing.

**Token economics:** Claude Code's sub-agent architecture means heavy tasks spawn multiple parallel agents, each consuming tokens. A complex refactor that takes 30 minutes might use 500K to 1M tokens. The Max tiers absorb this without per-token billing.

### Cursor

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Hobby | Free | Limited models | 2,000 completions/mo |
| Pro | $20 | GPT-4o, Claude Sonnet, Cursor models | 500 fast requests/mo, unlimited slow |
| Pro+ | $60 | All models + priority | 1,500 fast requests/mo |
| Ultra | $200 | All models + max priority | 3,000 fast requests/mo |
| Business | $40/seat | All models | Team features, admin controls |

**What the pricing page does not tell you:** The "fast requests" metric is the real currency. A fast request uses frontier models with low latency. When you exhaust fast requests, you drop to slow mode, which uses cheaper models and queues your requests behind paying users. The experience degrades noticeably.

At $20/month with 500 fast requests, a developer making 30 to 40 agent interactions per day will exhaust their allocation in roughly two weeks. The remaining two weeks are spent on slow requests, which means weaker models and higher latency.

The Pro+ tier at $60 fixes this for most developers. Ultra at $200 is comparable to Claude Code Max but within the IDE instead of the terminal.

**Hidden cost:** [Cursor](/blog/what-is-cursor-ai-code-editor-2026)'s BYOK (Bring Your Own Key) option lets you use your own API keys for unlimited requests. This sounds like a hack, but API costs for heavy Cursor usage can easily exceed $100/month, making it more expensive than Pro+ while adding the complexity of managing API billing separately.

### GitHub Copilot

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Free | $0 | GPT-4o (limited) | 2,000 completions, 50 chat messages/mo |
| Pro | $10 | GPT-4o, Claude Sonnet | Unlimited completions, 300 chat/mo |
| Pro+ | $39 | All models + Opus/o1 | Unlimited completions, 1,500 chat/mo |
| Business | $19/seat | All models | Org management, IP indemnity |
| Enterprise | $39/seat | All models | SSO, audit logs, custom policies |

**What the pricing page does not tell you:** [Copilot](/blog/github-copilot-coding-agent-cli-2026)'s free tier is genuinely useful for autocomplete. The 2,000 completions per month covers light usage. But the 50 chat messages per month is almost nothing for agentic workflows. One complex task might require 10 to 15 back-and-forth messages.

Copilot's strongest advantage is ecosystem integration. It works inside VS Code, JetBrains, Neovim, and Xcode. It reads your repository structure via GitHub. For teams already on GitHub Enterprise, the $39/seat Enterprise tier includes IP indemnity and compliance features that other tools do not offer at any price.

**Weakness:** Copilot's agentic capabilities trail Claude Code and Cursor. It excels at autocomplete and inline suggestions but falls behind on complex multi-file refactors and autonomous task execution.

### Windsurf (Codeium)

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Free | $0 | Codeium models | Generous autocomplete, limited Cascade |
| Pro | $15 | SWE-1 + frontier models | Unlimited Cascade flows |
| Enterprise | Custom | All models + on-prem | Custom limits, compliance |

**What the pricing page does not tell you:** Windsurf's $15 Pro tier is the best value entry point in the market. You get unlimited access to their Cascade multi-step agent, which handles sequential tasks well. The SWE-1 model is purpose-built for coding and handles routine development work competently.

The tradeoff is model ceiling. Windsurf does not offer Opus-class reasoning. For complex architectural decisions or nuanced refactors, the model quality gap becomes apparent. Windsurf is excellent for the 80% of coding work that is straightforward and struggles with the 20% that requires deep reasoning.

**Free tier generosity:** Windsurf's free tier is the most generous in the market for autocomplete. If you only need fast completions and occasional agent interactions, you can use Windsurf productively without paying.

### OpenAI Codex

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Via ChatGPT Plus | $20 | GPT-4o + Codex | Shared ChatGPT limits |
| Via ChatGPT Pro | $200 | GPT-5.3 + Codex | Higher limits, priority |
| API | Usage-based | All models | Per-token billing |

**What the pricing page does not tell you:** Codex operates differently from every other tool on this list. It runs in a cloud sandbox, not on your local machine. Your repository is cloned to OpenAI's infrastructure, and the agent executes in an isolated environment. This means it can run tests, install dependencies, and execute code without touching your local setup.

The implication for pricing is that you are paying for both the model and the compute. The $20 ChatGPT Plus tier gives you access but with shared limits across all ChatGPT features. Heavy Codex usage during a coding session might exhaust your allocation, leaving you without ChatGPT access for other tasks.

The $200 tier provides the best model access (GPT-5.3) and higher limits. For developers who want OpenAI's strongest model applied to coding tasks, this is the tier. But the cloud-only execution model means latency for file operations, and you cannot use it offline.

### Augment

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Dev | Free | Claude, GPT models | 96,000 credits/mo |
| Individual Pro | $50 | All models + priority | Higher limits |
| Enterprise | Custom | All models | Team features |

**What the pricing page does not tell you:** Augment's free Dev tier is remarkably generous. 96,000 credits per month covers substantial usage, and the credit system abstracts away per-model pricing. You pick the best model for each task without worrying about which model costs more per token.

Augment supports multiple models through a single interface. You can use Claude Sonnet for fast iterations and GPT-5 for complex reasoning without switching tools or managing separate subscriptions. This flexibility is unique in the market.

**Credit economics:** Different models consume credits at different rates. A Claude Sonnet request might cost 1 credit while a GPT-5.3 request costs 5. Understanding the credit conversion rates for your preferred models determines how far 96,000 credits actually go.

### Gemini CLI

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Free | $0 | Gemini 2.5 Pro | 60 requests/min, 1,000/day |
| Via Google AI Studio | $0 | Gemini 2.5 Pro | Higher limits |
| Ultra (Google One AI) | $250 | Gemini Ultra | Highest limits |

**What the pricing page does not tell you:** Gemini CLI is completely free for most developers. The free tier limits of 60 requests per minute and 1,000 per day are sufficient for heavy daily use. There is no $20/month tier because there does not need to be.

The catch is model quality. Gemini 2.5 Pro is competent but generally ranks below Claude Opus and GPT-5.3 on complex coding benchmarks. For straightforward coding tasks, the price-to-performance ratio is unbeatable. For tasks requiring deep reasoning, you may find yourself spending more time on corrections than you save on subscription costs.

### Zed AI

| Tier | Monthly Cost | Model Access | Usage |
|------|-------------|--------------|-------|
| Editor | Free | None (editor only) | N/A |
| Zed AI | $20 | Claude Sonnet, GPT-4o | Fair-use limits |

**What the pricing page does not tell you:** Zed is an editor first, AI tool second. The $20 AI add-on gives you inline assistance and chat within a fast, native editor. The AI capabilities are competent but not the primary value proposition. You are paying for the best code editor available (performance, multiplayer, extensibility) that happens to have AI built in.

## The Decision Matrix

Pricing alone does not determine value. The right tool depends on how you work. Here is the decision matrix for five common developer profiles.

### Profile 1: Solo Founder Building a SaaS

**Daily pattern:** 4 to 8 hours of coding, full-stack work, frequent context switches between features, deployment, and bug fixes.

**Best choice:** Claude Code Max ($100 or $200/month)

**Why:** Solo founders need the strongest reasoning model because they do not have teammates to catch architectural mistakes. Claude Code's codebase-wide context means it understands the full project. The autonomous execution means you can spec a feature and let it build while you work on something else. The $100 to $200 monthly cost replaces what would otherwise be a $5,000 to $10,000/month junior developer.

**Runner-up:** Cursor Pro+ ($60/month) if you prefer visual diffs and IDE-native workflows.

### Profile 2: Professional Developer on a Team

**Daily pattern:** 2 to 4 hours of coding, code review, meetings, documentation. Working within an established codebase with conventions.

**Best choice:** GitHub Copilot Pro ($10/month) or Cursor Pro ($20/month)

**Why:** Team developers benefit most from tools that integrate with existing workflows. Copilot's GitHub integration means it understands your repo, your PRs, and your team's patterns. At $10/month, it is effectively free relative to a developer salary. Cursor Pro at $20/month adds stronger agentic capabilities for when you need multi-file changes.

**Runner-up:** Augment Free tier if your team does not standardize on a single tool and you want multi-model access without per-seat costs.

### Profile 3: Budget-Conscious Learner

**Daily pattern:** 1 to 2 hours of coding, learning new technologies, building side projects.

**Best choice:** Gemini CLI (free) plus Windsurf Free tier

**Why:** Both are genuinely free with generous limits. Gemini CLI handles terminal-based agent work. Windsurf handles IDE autocomplete and occasional agent interactions. Together they cover the full development experience at zero cost.

**Runner-up:** GitHub Copilot Free tier for VS Code users who want the simplest setup.

### Profile 4: AI-Heavy Power User

**Daily pattern:** 6 or more hours of AI-assisted coding, running overnight agents, parallel agent workflows, shipping multiple features per day.

**Best choice:** Claude Code Max $200/month

**Why:** At this usage level, any tool with per-request or per-credit limits will throttle you. The $200 Max tier is the only option that provides effectively unlimited access to Opus-class reasoning. Power users report running Claude Code for 8 or more hours daily without hitting meaningful limits.

**Runner-up:** Cursor Ultra ($200/month) if you cannot work outside an IDE.

### Profile 5: Enterprise Team Lead

**Daily pattern:** Evaluating tools for a team of 10 or more developers. Compliance, security, and cost predictability matter more than individual productivity.

**Best choice:** GitHub Copilot Enterprise ($39/seat/month) or Cursor Business ($40/seat/month)

**Why:** Enterprise tiers provide admin controls, audit logs, IP indemnity, and SSO. These features do not make individual developers faster, but they make the tool deployable across an organization. GitHub Copilot Enterprise wins on GitHub integration. Cursor Business wins on agentic capabilities.

**Runner-up:** Augment Enterprise for teams that want multi-model access with centralized billing.

## Hidden Costs Nobody Talks About

### Context Switching Cost

Using multiple tools is not free even when the tools themselves are cheap. Every context switch between tools loses state, breaks flow, and requires re-establishing context. A developer using Copilot for autocomplete, Cursor for refactoring, and Claude Code for complex tasks is paying three subscriptions and paying the cognitive tax of switching between three interfaces.

The cheapest total cost is often one tool at a higher tier rather than three tools at lower tiers.

### Overage and Throttling Cost

Most tools throttle gracefully, meaning they slow down instead of cutting you off. But slow AI assistance during a critical coding session is more expensive than no assistance. You wait for responses, lose your train of thought, and end up doing the work manually anyway. The subscription cost is wasted.

If you regularly hit throttling limits, you are on the wrong tier. The cost of upgrading is almost always less than the productivity lost to throttling.

### Lock-In Cost

Some tools create dependency through proprietary features. Cursor rules files do not transfer to Claude Code. Claude Code CLAUDE.md files do not transfer to Copilot. Skills built for one tool are not portable to another.

This is not a reason to avoid investing in tool-specific configuration. But it is a reason to prefer tools with open, portable configuration formats. CLAUDE.md is a markdown file that any tool can read. Proprietary config formats create switching costs.

### API Key Management Cost

BYOK (Bring Your Own Key) options sound like they save money. In practice, they add complexity: managing API keys, monitoring usage, setting billing alerts, and reconciling costs across multiple providers. For individual developers, the subscription model is almost always cheaper and simpler than BYOK.

## The Pricing Trend

Three trends are reshaping AI coding tool pricing in 2026.

**Subscriptions are replacing per-token billing** for individual developers. The mental overhead of per-token billing discourages experimentation. Developers on subscription plans use AI more aggressively and get better results. Every major tool now offers a flat-rate tier.

**Free tiers are getting more generous.** Gemini CLI, Augment Dev, Windsurf Free, and Copilot Free all provide meaningful functionality at zero cost. The competition for developer adoption is driving free tier quality up. For light users, there has never been a better time to use AI coding tools.

**The premium tier is converging at $200/month.** Claude Code Max, Cursor Ultra, and ChatGPT Pro all hit $200. This is not a coincidence. It represents what the market will pay for the best individual developer experience with the strongest models and the highest usage limits. Below $200, you get compromises. At $200, you get everything.

## Bottom Line

The right tool at the right tier costs less than you think and delivers more than you expect. The wrong tool at any tier wastes money and time.

For most developers, the answer is simpler than the pricing pages suggest: pick one tool, invest in the tier that matches your usage, and stop worrying about optimizing across multiple subscriptions. The productivity gain from mastering one tool deeply outweighs the savings from arbitraging pricing across three.

If you are starting from zero: Gemini CLI (free) to learn the workflow. If you are ready to invest: Claude Code at $100/month or Cursor at $60/month. If AI is your primary development method: Claude Code at $200/month. That is the decision tree for 90% of developers.

Decision pages to read next:

- [AI coding tools comparison matrix 2026](/blog/ai-coding-tools-comparison-matrix-2026) - broad feature and workflow comparison.
- [Claude Code vs Cursor vs Codex](/blog/claude-code-vs-cursor-vs-codex-2026) - best next read for the core three-tool decision.
- [Claude Code vs Cursor](/blog/claude-code-vs-cursor-2026) - terminal agent vs IDE-native workflow.
- [Cursor vs Codex](/blog/cursor-vs-codex) - IDE agent vs OpenAI terminal/cloud agent.
- [Codex vs Claude Code](/blog/codex-vs-claude-code-april-2026) - OpenAI vs Anthropic for autonomous coding.
- [Windsurf vs Cursor](/blog/windsurf-vs-cursor) - budget-friendly IDE agent vs the category leader.
- [Aider vs Claude Code](/blog/aider-vs-claude-code-2026-update) - open-source CLI workflow vs managed agent workflow.
- [Best AI coding tools 2026](/blog/best-ai-coding-tools-2026) - ranking after you understand the pricing.

## Frequently Asked Questions

### Which AI coding tool has the best free tier?

Gemini CLI and Windsurf offer the most generous free tiers. Gemini CLI provides 60 requests per minute and 1,000 per day with Gemini 2.5 Pro - enough for heavy daily use at zero cost. Windsurf's free tier includes unlimited autocomplete and limited Cascade agent access. For VS Code users, GitHub Copilot Free gives 2,000 completions and 50 chat messages per month.

### Is the $200/month tier worth it for individual developers?

Yes, if AI is your primary development method and you code 6+ hours daily. At that usage level, cheaper tiers will throttle you. The $200 tier (Claude Code Max 20x or Cursor Ultra) provides effectively unlimited access to the best models. Developers running complex refactors, parallel agents, or overnight tasks often find the productivity gain pays for itself within a week.

### What happens when I hit usage limits on these tools?

Most tools throttle rather than cut off. You drop to slower models, longer wait times, or queued requests. Claude Code Pro users get throttled during peak hours. Cursor Pro users exhaust fast requests and fall back to slow mode with weaker models. Copilot chat limits hard-stop at 300 messages on Pro. The experience degrades enough that upgrading usually makes more sense than suffering through the remaining billing cycle.

### Should I use my own API keys (BYOK) to save money?

Rarely. BYOK sounds cheaper but adds complexity: key management, usage monitoring, billing alerts, and reconciling costs across providers. For heavy users, API costs easily exceed $100-200/month anyway - the same as subscription tiers that include better UX and support. BYOK only makes sense for teams with existing API infrastructure or developers who need specific model versions not offered in subscription tiers.

### Which tool is best for teams with compliance requirements?

GitHub Copilot Enterprise ($39/seat) or Cursor Business ($40/seat). Both offer SSO, audit logs, admin controls, and usage analytics. Copilot Enterprise adds IP indemnity - legal protection if generated code infringes patents or copyrights. For regulated industries or companies with strict security policies, these enterprise tiers are the only deployable options.

### Can I use multiple AI coding tools together effectively?

You can, but the context switching cost often exceeds the savings. Each tool switch breaks your flow and loses state. A developer paying $20 each for Copilot, Cursor, and Claude Code spends $60/month and deals with three interfaces. That same $60 on Cursor Pro+ gets a unified experience with stronger capabilities. The exception: using a free tier tool (Gemini CLI) alongside a paid tool for specific tasks can work if you keep context switches minimal.

### How do I know which tier is right for my usage level?

Track your actual usage for a week. Count how many AI interactions you make per day - not just chats, but completions, refactors, and agent runs. If you average under 20 interactions daily, free or $20 tiers work. If you hit 50-100 interactions, you need $60-100 tiers. Over 100 interactions and you need $200 tiers. Hitting throttling before month-end means you are on the wrong tier.

### Why do AI coding tools cost around $200/month at the top tier?

The $200 price point reflects the cost of providing unlimited access to frontier models (Opus, GPT-5.x) for heavy users. At API rates, 8 hours of daily Opus usage would cost thousands per month. The subscription absorbs this variance - light users subsidize heavy users. Competition keeps the price converging: Claude Code Max, Cursor Ultra, and ChatGPT Pro all land at $200 because that is what power users will pay for the best experience without usage anxiety.


The AI-Native Development Workflow: How Top Developers Actually Work in 2026
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
There is a growing gap between developers who use AI tools and developers who work AI-natively. The first group bolts AI onto their existing workflow. They use [Copilot](/blog/github-copilot-coding-agent-cli-2026) for autocomplete, occasionally paste code into ChatGPT, and consider themselves AI-assisted. Their productivity increases by 20 to 30 percent.

The second group has restructured their entire workflow around [AI agent](/blog/ai-agents-explained) capabilities. They plan differently, build differently, review differently, and deploy differently. Their productivity increases by 5x to 10x. The difference is not the tools. It is the workflow.

This is what AI-native development actually looks like in 2026. Not a tool recommendation list, but a workflow definition based on how the most productive developers operate.

## The Five-Layer Stack

AI-native development operates across five layers. Each layer has a primary tool, a primary function, and a specific role in the development cycle.

```
Layer 5: Execution    - Cron agents, overnight agents, CI/CD agents
Layer 4: Data         - Context files, memory systems, skill libraries
Layer 3: Review       - Code review, diff analysis, merge decisions
Layer 2: IDE          - Visual editing, file navigation, UI work
Layer 1: Terminal     - Primary agent, codebase operations, orchestration
```

Most developers operate on Layers 1 and 2 only. They have a terminal agent and an IDE. The developers who achieve 10x productivity operate across all five layers simultaneously.

### Layer 1: The Terminal Agent

The terminal is the command center of AI-native development. Not because the terminal is inherently better than an IDE, but because terminal agents have the widest operational surface. They can read any file, execute any command, modify any part of the codebase, and spawn sub-processes. No permission dialogs. No sandboxing. Full system access.

[Claude Code](/blog/what-is-claude-code) is the reference implementation of a terminal agent. It reads the entire codebase, understands the project structure, edits files, runs tests, commits code, and operates autonomously for extended periods. The terminal agent handles the majority of coding work: feature implementation, bug fixes, refactoring, test writing, and infrastructure changes.

The terminal agent's workflow is prompt-driven:

```
> Implement user preferences with a settings page. Read the existing
  patterns in src/actions/ and src/components/ and follow them.
  Add a preferences table to the schema. Create server actions for
  CRUD operations. Build the settings UI. Write tests.
```

A single prompt like this triggers a multi-step execution that would take a developer 1 to 2 hours manually. The agent reads the codebase, understands the patterns, implements the feature across multiple files, and verifies its work. The developer reviews the output instead of writing it.

**Key practices for Layer 1:**

- Always start with plan mode. Have the agent outline its approach before executing.
- Provide project context via CLAUDE.md. The agent should know your architecture, conventions, and constraints before it writes a line of code.
- Let the agent complete its work before intervening. Frequent interruptions break multi-step reasoning.
- Use [sub-agents](/blog/claude-code-sub-agents) for independent tasks within a larger feature.

### Layer 2: The IDE

The IDE is the visual layer. It provides file navigation, syntax highlighting, diff visualization, and the ability to make targeted edits across multiple files simultaneously.

In an AI-native workflow, the IDE is not the primary authoring tool. It is the primary review and navigation tool. The terminal agent writes most of the code. The IDE lets you see what changed, navigate the codebase visually, and make quick adjustments that are faster to type than to describe.

[Cursor](/tools/cursor) is the most popular IDE for AI-native development because it combines traditional editing with agent capabilities. But the key insight is that the IDE agent and the terminal agent serve different functions:

| Capability | Terminal Agent | IDE Agent |
|-----------|---------------|-----------|
| Full codebase context | Yes | Partial (open files + index) |
| Autonomous execution | Yes (minutes to hours) | Yes (seconds to minutes) |
| Multi-file refactoring | Yes | Yes |
| Visual diff review | No (text output) | Yes |
| UI/component work | Possible but slow | Fast (visual feedback) |
| Command execution | Full system access | Sandboxed |

The optimal workflow uses both: terminal agent for implementation, IDE agent for review and visual adjustments.

**Key practices for Layer 2:**

- Use the IDE to review terminal agent output, not to duplicate its work.
- For UI work, the IDE's visual feedback loop is faster. Switch to the IDE for component styling, layout adjustments, and visual polish.
- Keep the IDE's AI features focused on targeted edits. "Change this button color" is an IDE task. "Refactor the authentication system" is a terminal task.

### Layer 3: The Review Layer

AI-native development generates code faster than traditional development. This means review becomes the bottleneck. The review layer is the process and tooling for evaluating agent-generated code before it ships.

Most developers review AI-generated code the same way they review human-written code: line by line, file by file. This is too slow for the volume of changes an agent produces. A 30-minute agent session might modify 20 files. Line-by-line review of 20 files takes longer than writing the code manually.

**Structured review** is the AI-native approach. Instead of reading every line, focus review on five risk categories:

1. **Security boundaries.** Does every API route check authentication? Are user inputs validated? Is data properly scoped to the requesting user?

2. **Data mutations.** What writes to the database? Are there race conditions? Is data integrity maintained?

3. **Error handling.** What happens when external services fail? Are errors caught and reported? Do users see helpful messages instead of stack traces?

4. **Type safety.** Are types properly defined? Any `any` types that should be specific? Do function signatures match their implementations?

5. **Business logic.** Does the implementation match the spec? Are edge cases handled? Do the numbers add up ([pricing](/blog/ai-coding-tools-pricing-2026), limits, calculations)?

Everything else - file structure, naming conventions, import ordering, code style - is low-risk and can be spot-checked rather than reviewed exhaustively.

**Key practices for Layer 3:**

- Review by risk category, not by file. Security first, then data mutations, then error handling.
- Use AI to review AI. Have a separate agent session analyze the diff for security issues, missing error handling, and type problems.
- Review the tests, not just the implementation. If the tests cover the risk categories, the implementation is more trustworthy.
- Time-box reviews. If a feature takes 5 minutes to specify and 30 minutes to build, the review should take 10 to 15 minutes, not an hour.

### Layer 4: The Data Layer

The data layer is what separates AI-assisted development from AI-native development. It is the persistent information architecture that makes every agent interaction smarter than the last.

The data layer has three components:

**Context files.** CLAUDE.md, project rules, architecture documents. These load at session start and give the agent awareness of the project before the first prompt.

**Memory systems.** MEMORY.md, session snapshots, correction logs. These accumulate knowledge across sessions. What was decided, what failed, what the developer prefers.

**Skill libraries.** Reusable instructions for specific tasks. Deployment procedures, testing strategies, content creation workflows. Skills encode expert knowledge in a format that any agent session can use.

The data layer is an investment that compounds. A project with no data layer requires the developer to re-explain context every session. A project with a mature data layer requires almost no re-explanation because the agent already knows everything it needs to know.

```
.claude/
  CLAUDE.md           # Project architecture and conventions
  MEMORY.md           # Accumulated knowledge and decisions
  skills/
    deploy.md         # Deployment procedure
    test.md           # Testing strategy
    review.md         # Code review checklist
    add-feature.md    # Feature implementation workflow
  context/
    2026-04-08.md     # Yesterday's session snapshot
    2026-04-07.md     # Day before
```

**Key practices for Layer 4:**

- Update context files as part of every significant change. If you change the database, update the architecture section of CLAUDE.md.
- Write session snapshots at the end of every working session. The next session reads them to pick up where you left off.
- Extract skills from repetitive tasks. If you have explained a process to the agent three times, it should be a skill.
- Prune aggressively. Outdated context is worse than no context because the agent follows it faithfully.

### Layer 5: The Execution Layer

The execution layer is where AI-native development becomes truly autonomous. Agents run without human supervision: overnight builds, scheduled maintenance, CI/CD pipelines, and monitoring agents.

**Overnight agents** handle tasks that benefit from uninterrupted execution. Before going to bed, you write a spec describing what needs to happen. An agent picks it up, executes it, and leaves a report for the morning. The spec format is crucial because the agent has no way to ask clarifying questions.

```markdown
## Overnight Spec: Add Export Feature

Objective: Users can export their data as CSV from the settings page.

Context:
- Data tables: users, cronJobs, cronRuns
- Export should include all user-owned data
- Use server actions, not API routes
- Follow existing patterns in src/actions/

Acceptance criteria:
- Export button on /settings page
- Clicking exports a .csv file to the browser
- CSV includes all cronJobs and their runs for the last 30 days
- Empty state handled (no data to export message)
- Tests pass: npm run test

Verification:
- Build passes: npm run build
- Tests pass: npm run test
- Dev server runs without errors
```

**Cron agents** handle recurring tasks. Daily dependency updates, scheduled database cleanup, periodic health checks, report generation. These run on a schedule and either handle the task silently or alert when human intervention is needed.

**CI/CD agents** extend traditional CI/CD with intelligence. Instead of fixed pipelines, agents analyze what changed and determine what needs testing, what needs review, and what can ship automatically.

**Key practices for Layer 5:**

- Write specs, not prompts. Specs have objectives, context, acceptance criteria, and verification steps. Prompts are ambiguous.
- Start with low-risk overnight tasks. Documentation updates, test coverage improvements, dependency updates. Build confidence before assigning critical features.
- Always include verification steps. The agent should prove its work is correct, not just claim it is.
- Review overnight output in the morning with fresh eyes. The combination of overnight execution and morning review consistently produces better outcomes than same-session execution and review.

## The Daily Rhythm

Here is what an AI-native development day looks like in practice.

### Morning (30 minutes)

1. Read the overnight agent report. Review what it built.
2. Read session snapshots from yesterday. Orient yourself.
3. Check the memory file for recent decisions and pending items.
4. Review the kanban board. Pick 2 to 3 priorities for the day.
5. Merge overnight work if it passes review. Deploy if appropriate.

### Deep Work Block 1 (2 to 3 hours)

1. Open the terminal agent. Load the highest-priority task.
2. Start with plan mode. Review the agent's proposed approach.
3. Approve and let the agent execute.
4. While the agent works on the primary task, switch to the IDE for a secondary task: visual polish, small bug fixes, UI adjustments.
5. Review the agent's output when it completes. Merge or request changes.
6. Commit after each completed feature.

### Midday (30 minutes)

1. Update MEMORY.md with morning decisions.
2. Write any new skills extracted from the morning work.
3. Update CLAUDE.md if architecture changed.
4. Quick deploy of completed features.

### Deep Work Block 2 (2 to 3 hours)

1. Continue with the day's priorities. Same terminal-agent-led workflow.
2. Use parallel worktrees if the remaining tasks are independent.
3. Run tests. Fix failures. Commit.

### Evening (30 minutes)

1. Write a session snapshot covering the day's work.
2. Write overnight specs for 1 to 2 tasks.
3. Start the overnight agents.
4. Update the kanban board.
5. Review tomorrow's priorities.

Total active coding time: 4 to 6 hours. Total agent-assisted output: equivalent to 20 to 40 hours of traditional development. The multiplier comes from the agent handling implementation while the developer focuses on decisions, reviews, and specifications.

## What Changes About the Developer's Job

AI-native development changes what skills matter.

### Skills That Matter More

**Specification writing.** The ability to describe what you want in precise, unambiguous terms. This is the new "coding." Developers who can write clear specs get better results from agents than developers who write vague prompts and then correct the output.

**Architecture thinking.** Agents implement. Developers architect. The ability to choose the right database, the right API pattern, the right state management approach, and the right service boundaries becomes more important when the implementation is automated.

**Review acumen.** Reading code quickly, identifying risk areas, and making merge decisions. The volume of code to review increases dramatically. Developers who can review 20 files in 15 minutes and catch the important issues are more productive than those who take an hour and catch everything.

**System design.** Designing the data layer, the skill library, and the agent workflows. This meta-skill determines how effectively the AI tools work for your specific projects.

### Skills That Matter Less

**Typing speed.** Irrelevant when the agent writes most of the code.

**Syntax memorization.** The agent knows the syntax. You do not need to remember whether it is `Array.prototype.flatMap` or `Array.prototype.flat().map()`.

**Boilerplate generation.** Scaffolding, configuration files, CRUD endpoints, form components. The agent handles all of this faster than any human can type it.

**Tool-specific expertise.** Deep knowledge of webpack configuration, Terraform syntax, or Docker networking. The agent has this knowledge. You need to know what you want, not how to express it in the tool's language.

### Skills That Stay the Same

**Debugging.** Agents help, but complex bugs still require human reasoning about system behavior, timing, and state.

**User empathy.** Understanding what users need and translating that into product requirements. No agent does this.

**Communication.** Explaining technical decisions to non-technical stakeholders. Writing documentation that humans can understand. Collaborating with teammates. For the boilerplate first draft of project docs, our [README generator](/readme-generator) handles the scaffolding so you can spend the time on the parts that need a human.

**Taste.** Knowing when something feels right or wrong. This applies to UI design, API design, error messages, and user flows. Agents optimize for correctness. Humans optimize for elegance.

## Common Anti-Patterns

### Anti-Pattern 1: AI as Autocomplete

Using AI agents for line-by-line suggestions instead of feature-level work. This captures 10% of the productivity gain and misses the other 90%. If your primary interaction with AI is accepting tab completions, you are leaving most of the value on the table.

### Anti-Pattern 2: No Context Investment

Starting every session by re-explaining the project. No CLAUDE.md, no memory file, no skills. Each session is a cold start. The agent makes mistakes it should not make because it does not know your conventions.

### Anti-Pattern 3: Over-Supervision

Watching the agent work and interrupting every few seconds. "No, use this import." "Wait, that is the wrong file." "Stop, let me explain." This is slower than writing the code yourself because you are paying the overhead of both human work and agent work without the benefit of either.

The fix: write a clearer spec and let the agent execute it. If the output is wrong, improve the spec for next time.

### Anti-Pattern 4: No Review

Blindly merging agent output because "the AI wrote it so it must be right." Agent code has consistent failure patterns that require human review. Skipping review does not save time. It creates bugs that take more time to fix than the review would have taken.

### Anti-Pattern 5: Single-Layer Operation

Using only the terminal agent or only the IDE agent. Each layer serves a different function. Using only one is like using only a hammer when you have a full toolbox.

## The Transition Path

Moving from traditional development to AI-native development is not an overnight switch. Here is the progression.

**Week 1: Terminal agent basics.** Install Claude Code or equivalent. Use it for one feature per day. Learn plan mode. Learn how to write effective prompts.

**Week 2: Context investment.** Write a CLAUDE.md for your main project. Start a MEMORY.md. Notice how the agent's output improves with context.

**Week 3: Review workflow.** Develop a structured review process. Practice reviewing by risk category. Time yourself to establish a baseline.

**Week 4: Parallel development.** Try worktrees. Run two agent sessions simultaneously on independent features. Experience the productivity jump from parallelism.

**Month 2: Data layer maturation.** Extract your first 5 to 10 skills. Write session snapshots consistently. Notice the cumulative effect of persistent context.

**Month 3: Execution layer.** Write your first overnight spec. Run your first cron agent. Extend your productive hours beyond the time you are at the keyboard.

Each step builds on the previous one. Skipping ahead (trying overnight agents before you have a solid CLAUDE.md) produces frustration because the foundation is not there. Follow the progression and each layer will feel natural by the time you reach it.

## The Productivity Multiplier

The five-layer stack is not about working harder. It is about applying leverage at every stage of the development process. The terminal agent provides implementation leverage. The IDE provides visual leverage. The review layer provides quality leverage. The data layer provides knowledge leverage. The execution layer provides time leverage.

Combined, these layers transform the developer's role from "person who writes code" to "person who directs code production." The output per hour increases not because the developer types faster but because every hour of developer attention produces 5 to 10 hours of agent execution.

This is what AI-native development means. Not using AI tools within a traditional workflow. Building a new workflow that could not exist without AI tools. The developers who make this transition are not just faster. They are operating on a different axis of productivity entirely.

## Frequently Asked Questions

### What is AI-native development?

AI-native development is a workflow where the entire development process is restructured around AI agent capabilities. Instead of using AI as an add-on to traditional coding, AI-native developers use terminal agents as their primary implementation tool, maintain persistent context through CLAUDE.md and memory files, and run execution-layer agents overnight. The productivity gain is 5x to 10x compared to traditional development, versus the 20 to 30 percent improvement from simply using AI for autocomplete.

### What is the difference between AI-assisted and AI-native development?

AI-assisted development bolts AI tools onto an existing workflow - Copilot for autocomplete, occasionally pasting code into ChatGPT. AI-native development restructures the entire workflow: the terminal agent handles implementation, the IDE handles visual review, the data layer stores persistent context, and the execution layer runs agents autonomously. The difference is not the tools but how work is organized around agent capabilities.

### How do I start with AI-native development?

Start with the terminal agent layer. Install [Claude Code](/blog/what-is-claude-code) or an equivalent tool and use it for one feature per day. In week two, write a CLAUDE.md file for your project to provide persistent context. Week three, develop a structured review process. Week four, try parallel worktrees. By month two, extract skills from repetitive tasks. Month three, write your first overnight spec. Each layer builds on the previous one.

### What is CLAUDE.md and why is it important?

CLAUDE.md is a project context file that loads at the start of every agent session. It contains your architecture decisions, coding conventions, and project constraints. Without it, you re-explain context every session. With a mature CLAUDE.md, the agent already knows your database schema, API patterns, and style preferences before the first prompt. It is the foundation of the data layer and makes every agent interaction smarter.

### What should my daily workflow look like?

Morning: review overnight agent output, read session snapshots, merge completed work. Deep work blocks: use the terminal agent for implementation, switch to the IDE for visual work, review and commit. Midday: update MEMORY.md and CLAUDE.md. Evening: write session snapshots, write overnight specs, start overnight agents. Total active time is 4 to 6 hours, with agent-assisted output equivalent to 20 to 40 hours of traditional development.

### How do I review AI-generated code efficiently?

Review by risk category, not by file. Check security boundaries first: authentication, input validation, data scoping. Then data mutations: database writes, race conditions, data integrity. Then error handling: external service failures, user-facing messages. Then type safety. Everything else - naming, imports, style - is low-risk and can be spot-checked. A feature that takes 30 minutes to build should take 10 to 15 minutes to review, not an hour.

### What are overnight agents and how do I use them?

Overnight agents run tasks while you sleep. You write a detailed spec with objectives, context, acceptance criteria, and verification steps. The agent picks it up, executes it, and leaves a report for the morning. Start with low-risk tasks: documentation updates, test coverage improvements, dependency updates. Always include verification steps so the agent proves its work is correct. Review overnight output with fresh eyes in the morning.

### What developer skills matter more in AI-native development?

Specification writing matters more - the ability to describe what you want in precise, unambiguous terms. Architecture thinking matters more because agents implement while developers design. Review acumen matters more because the volume of code to review increases. System design for the data layer and skill libraries matters more. Typing speed, syntax memorization, and boilerplate generation matter less because agents handle these automatically.


Building Multi-Agent Workflows in Claude Code: A Practical Tutorial
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
## Why Multi-Agent Workflows Matter in Claude Code

A single [Claude Code](/blog/what-is-claude-code-complete-guide-2026) session is powerful. But it processes tasks sequentially. While it researches an API, it is not writing code. While it writes code, it is not running tests. The ceiling on any single session is one task at a time, and complex projects have dozens of independent tasks that could run simultaneously.

Multi-agent workflows break through that ceiling. Instead of one agent doing everything in sequence, you orchestrate a team of specialists. A researcher fetches documentation while an implementer scaffolds modules while a tester writes test cases. Three streams of work running in parallel, converging when they need to.

Claude Code has native support for this through three mechanisms: the Task tool (for spawning parallel [sub-agents](/blog/claude-code-sub-agents) within a session), custom sub-agents (for reusable specialists defined in markdown), and worktrees (for running independent Claude Code sessions on separate git branches). This tutorial covers all three with real examples you can use today.

## The Task Tool: Parallel Sub-Agents

The Task tool is Claude Code's built-in mechanism for delegating work to parallel agents. When you give Claude Code a complex instruction, it can spawn up to 7 sub-agents simultaneously, each working on a portion of the problem.

You do not need to configure anything. The Task tool is available by default. The key is learning how to prompt Claude Code so it chooses to parallelize rather than work sequentially.

### Prompts That Trigger Parallelism

The difference between sequential and parallel execution often comes down to how you phrase the request.

**Sequential (slow):**
```
Add error handling to the API routes, then update the tests, then update the docs.
```

Claude Code reads "then" as a dependency chain and executes step by step.

**Parallel (fast):**
```
Do these three things in parallel:
1. Add error handling to all API routes in src/api/
2. Update the test suite in tests/ to cover the new error cases
3. Update the API documentation in docs/api.md with error response codes
```

The explicit "in parallel" instruction combined with numbered independent tasks tells Claude Code to spawn three Task agents.

**Even better - give context on independence:**
```
These tasks are independent and can run simultaneously:
1. Research the Stripe Billing API for usage-based pricing - just read docs, don't write code
2. Scaffold the database schema for a usage tracking system in src/db/schema.ts
3. Create the API route handlers in src/api/billing/ with placeholder logic

None of these depend on each other. Fan out.
```

### Real Workflow: Feature Implementation

Here is how a real feature implementation looks when you lean into parallelism. Say you need to add a notifications system to a [Next.js](/blog/nextjs-ai-app-stack-2026) app.

**Step 1: Research + scaffold in parallel**

Prompt:
```
I need to add a notifications system. Run these in parallel:

1. Research: look at our existing database schema in src/db/schema.ts
   and figure out what tables we need for notifications (read-only, no changes)

2. Research: check how we handle real-time updates elsewhere in the codebase -
   search for any WebSocket, SSE, or polling patterns we already use

3. Scaffold: create the empty file structure we'll need:
   - src/api/notifications/route.ts
   - src/components/NotificationBell.tsx
   - src/components/NotificationList.tsx
   - src/lib/notifications.ts
   - tests/notifications.test.ts
   Just create the files with TODO comments, no implementation yet.
```

Claude Code spawns three Task agents. Two research agents read the codebase (read-only, safe to parallel) while a third creates the file structure. All three finish in roughly the time it would take one to complete a single task.

**Step 2: Implement in parallel**

Once the research is done and the files exist, the next prompt builds on those results:

```
Based on the research results, implement these in parallel:

1. Database layer: add the notifications table to src/db/schema.ts
   and create the query functions in src/lib/notifications.ts
   (createNotification, getUnread, markAsRead, markAllRead)

2. API routes: implement the REST endpoints in src/api/notifications/route.ts
   GET /api/notifications - list unread
   POST /api/notifications/:id/read - mark one as read
   POST /api/notifications/read-all - mark all as read

3. UI components: build NotificationBell (icon with unread count badge)
   and NotificationList (dropdown with notification items, mark-as-read buttons)
   Use our existing design system components.

4. Tests: write tests for the database query functions and API routes.
```

Four agents work simultaneously. The database and API agents are writing different files. The UI agent works in the components directory. The test agent writes to the test directory. No conflicts because each agent operates in its own file scope.

### When Task Agents Conflict

Parallel agents work best when they touch different files. When two agents need to modify the same file, you get merge conflicts or one agent's changes overwrite the other's.

**Avoid this pattern:**
```
In parallel:
1. Add the notifications table to schema.ts
2. Add the billing table to schema.ts
```

Both agents modify the same file. One will win, and the other's changes disappear.

**Do this instead:**
```
Add both the notifications and billing tables to schema.ts.
Include all columns, indexes, and relations for both tables.
```

Let a single agent handle the file. Reserve parallelism for independent file scopes.

## Custom Sub-Agents: Reusable Specialists

The Task tool spawns generic agents. Custom sub-agents let you define specialists with specific expertise, tool access, and behavioral rules. They live as markdown files in `.claude/agents/` and persist across sessions.

### Creating Your First Sub-Agent

Type `/agents` in Claude Code to create a new agent interactively, or create the markdown file directly:

```markdown

---
name: researcher
description: Deep research on technical topics using web search and documentation
tools:
  - WebSearch
  - WebFetch
  - Read
  - Grep
  - Glob
---

You are a technical research specialist for a software development team.

## What you do
- Search the web for current documentation, release notes, and best practices
- Read local files to understand existing codebase patterns
- Cross-reference multiple sources to verify accuracy
- Return structured findings with source URLs

## What you never do
- Modify any files (you have read-only access to the codebase)
- Write code (that's the implementer's job)
- Make architectural decisions (that's the orchestrator's job)

## Output format
Always structure your findings as:
1. Summary (3-5 sentences)
2. Key findings (bulleted list)
3. Code examples (if applicable)
4. Sources (URLs)
5. Caveats or known issues
```

```markdown

---
name: implementer
description: Writes production TypeScript/React code following project conventions
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

You are a senior TypeScript developer.

## Rules
- Read CLAUDE.md before writing any code
- Follow existing patterns in the codebase - match style, naming, structure
- Always include TypeScript types - no `any` unless absolutely necessary
- Handle errors explicitly - no silent catches
- Write code that is readable first, clever never

## Before writing code
1. Check if a similar pattern exists in the codebase (use Grep)
2. Read the files you plan to modify (use Read)
3. Understand the project structure (use Glob on relevant directories)

## After writing code
- Verify the file compiles by running the appropriate build/lint command
- If you created a new module, check that it's exported from the barrel file
```

```markdown

---
name: tester
description: Writes and runs tests for TypeScript/React projects
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

You are a test engineer.

## Approach
- Write tests that verify behavior, not implementation
- Cover the happy path first, then edge cases, then error cases
- Use descriptive test names that read like documentation
- Mock external dependencies, never real APIs

## Process
1. Read the source code you're testing
2. Identify the public API surface
3. Write tests for each public function/component
4. Run the tests to verify they pass
5. If a test fails, fix the test or report the bug - never skip a failing test
```

### Using Sub-Agents in Practice

Once defined, Claude Code automatically delegates to sub-agents when it recognizes a matching task. You can also explicitly invoke them:

```
Use the researcher agent to find the current best practices
for implementing rate limiting in Next.js API routes.
```

Or reference them in a parallel workflow:

```
Fan out to these agents:
- researcher: find how Stripe handles webhook signature verification in Node.js
- implementer: create src/api/webhooks/stripe/route.ts with basic POST handler structure
- tester: write tests for webhook signature verification in tests/webhooks.test.ts
```

### The Agent Library Pattern

Over time, you build a library of specialists. Here are agents that work well for most TypeScript/Next.js projects:

| Agent | Tools | Purpose |
|-------|-------|---------|
| `researcher` | WebSearch, WebFetch, Read | Find docs, patterns, and best practices |
| `implementer` | Read, Write, Edit, Bash | Write production code |
| `tester` | Read, Write, Edit, Bash | Write and run tests |
| `reviewer` | Read, Grep, Glob | Code review without modifications |
| `documenter` | Read, Write, Edit | Write and update documentation |
| `debugger` | Read, Bash, Grep | Investigate bugs, read logs, trace issues |
| `migrator` | Read, Write, Edit, Bash, WebSearch | Handle dependency upgrades and migrations |

Keep agent files in version control. Share them across projects by placing global agents in `~/.claude/agents/`. Project-specific agents go in `.claude/agents/` at the project root.

## Worktrees: True Parallel Sessions

Task agents and sub-agents run within a single Claude Code session. Worktrees take parallelism further by running completely independent Claude Code sessions on separate git branches.

### The Setup

Git worktrees let you check out multiple branches simultaneously in different directories. Each worktree is a full working copy of your repo.

```bash
# Create worktrees for parallel feature development
git worktree add ../myproject-notifications feature/notifications
git worktree add ../myproject-billing feature/billing
git worktree add ../myproject-onboarding feature/onboarding
```

Now you have four directories:
- `myproject/` - your main branch
- `myproject-notifications/` - the notifications feature branch
- `myproject-billing/` - the billing feature branch
- `myproject-onboarding/` - the onboarding feature branch

### Running Parallel Sessions

Open a Claude Code session in each worktree. Each session is completely independent - different branch, different files, different agent context.

```bash
# Terminal 1
cd ../myproject-notifications && claude

# Terminal 2
cd ../myproject-billing && claude

# Terminal 3
cd ../myproject-onboarding && claude
```

Give each session its own task:

**Session 1 (notifications):**
```
Build a complete notifications system:
- Database table for notifications (type, message, read status, timestamps)
- API routes for CRUD operations
- NotificationBell component with unread count
- NotificationList dropdown component
- Mark as read functionality
```

**Session 2 (billing):**
```
Implement usage-based billing with Stripe:
- Usage tracking table in the database
- Stripe metered billing integration
- Usage dashboard component showing current period consumption
- API routes for usage data
```

**Session 3 (onboarding):**
```
Build a 4-step onboarding flow:
- Step 1: Profile info (name, role, company)
- Step 2: Preferences (notification settings, timezone)
- Step 3: Integrations (connect GitHub, Slack)
- Step 4: Team invite
- Progress indicator, skip/back/next navigation
```

Three features developed simultaneously. When each is done, you merge the branches:

```bash
git checkout main
git merge feature/notifications
git merge feature/billing
git merge feature/onboarding
git worktree remove ../myproject-notifications
git worktree remove ../myproject-billing
git worktree remove ../myproject-onboarding
```

### When to Use Worktrees vs Task Agents

**Use Task agents when:**
- Subtasks take seconds to minutes
- Agents need to share context (reading the same codebase state)
- The work is within a single feature or scope
- You want a single conversation tracking all the work

**Use worktrees when:**
- Features take 30+ minutes of agent time
- Features are completely independent (different files, different concerns)
- You want full session isolation (separate conversation history, separate branch state)
- You are building multiple features in parallel for a sprint

## Advanced Patterns

### The Scout-Build-Verify Pattern

This is the most reliable pattern for feature development. Three phases, each leveraging parallelism where possible.

**Phase 1: Scout (parallel research)**
```
Before writing any code, research these in parallel:
1. Read our current auth middleware and understand the pattern
2. Search for how we handle API errors in existing routes
3. Check what database migration tooling we use
4. Look at our test setup - framework, conventions, coverage config
Report findings. Do not modify anything.
```

**Phase 2: Build (parallel implementation)**
```
Based on the scout findings, implement in parallel:
1. Database migration and schema changes
2. API route handlers (separate files per resource)
3. UI components (separate files per component)
Each agent should reference the scout findings for consistency.
```

**Phase 3: Verify (parallel testing)**
```
In parallel:
1. Run the existing test suite to check for regressions
2. Write and run new tests for the features we just built
3. Run the linter and type checker on all modified files
4. Do a manual review of all changes - read every modified file
   and flag anything that looks wrong
```

### The Iteration Loop

For complex features, repeat the scout-build-verify cycle with increasing specificity:

```
Iteration 1: "Build the basic notifications system" (broad strokes)
Iteration 2: "Add real-time updates via SSE to the notification system" (specific enhancement)
Iteration 3: "Add notification preferences and quiet hours" (feature refinement)
Iteration 4: "Performance test the notification system under load" (hardening)
```

Each iteration uses the scout-build-verify pattern internally. The outer loop ensures you build incrementally rather than trying to ship everything at once.

### CLAUDE.md as Agent Contract

Your CLAUDE.md file is not just configuration - it is the contract that every agent (Task agent, sub-agent, or worktree session) reads before starting work. Put your coordination rules there:

```markdown
## Agent Coordination Rules

### File Ownership
When running parallel agents, each agent owns specific directories:
- Database work: src/db/ and migrations/
- API work: src/api/ (one agent per resource subdirectory)
- UI work: src/components/ (one agent per component file)
- Tests: tests/ (mirrors the src/ structure)

Never have two agents modify the same file simultaneously.

### Commit Convention
Each agent should commit its work with a prefix:
- [research] for research-only tasks
- [feat] for new features
- [test] for test additions
- [fix] for bug fixes
- [docs] for documentation

### Quality Gates
Before marking a task complete, every agent must:
1. Run `npm run typecheck` on modified files
2. Run `npm run lint` on modified files
3. Verify no console.log statements remain in production code
```

Every agent session reads this file. It creates consistency across parallel workers without explicit communication between them.

### The Daily Development Workflow

Here is the workflow I use daily for building features with Claude Code multi-agent patterns:

**Morning: Plan and scout**
```
Read the project kanban at [path]. Pick the top 3 tickets.
For each ticket, do a quick scout: read relevant files,
identify what needs to change, estimate complexity.
Give me a summary of what we're building today.
```

**Implementation: Parallel build**
```
Let's build [ticket 1]. Fan out:
1. Research agent: check docs for [dependency] we need
2. Implementer: scaffold the file structure
3. Tester: write test stubs based on the ticket acceptance criteria
```

Then for the main implementation:
```
Now implement. The research is done, file structure exists, test stubs are ready.
Run implementer and tester in parallel:
- Implementer: fill in the actual logic for each file
- Tester: flesh out the test stubs into real tests as the implementer finishes files
```

**End of day: Verify and clean up**
```
In parallel:
1. Run the full test suite
2. Run linting and type checking
3. Review all changes made today - read every modified file
4. Update the project kanban with completed/in-progress status
```

## Troubleshooting

### "Claude Code is not parallelizing my tasks"

Check your prompt. If tasks have implicit dependencies ("do X then Y"), Claude Code serializes them. Rephrase to make independence explicit: "These are independent. Run simultaneously."

### "Sub-agents keep re-reading files the orchestrator already read"

This is expected. Each Task agent has its own context window. The orchestrator's context is not shared. If an agent needs information the orchestrator found, include it in the task prompt explicitly.

### "Worktree sessions conflict when I merge"

Keep features scoped to separate directories. If two features must touch the same file (like a shared schema), make one depend on the other - merge the first branch before starting the second.

### "My agents produce inconsistent code styles"

Your CLAUDE.md is the fix. Add explicit style rules, link to examples in the codebase, and include a "before you write code, read these files" instruction. Every agent reads CLAUDE.md, so shared conventions propagate automatically.

## What This Looks Like at Scale

A typical feature that takes 2-3 hours with sequential Claude Code usage can drop to 45-60 minutes with multi-agent workflows. The time savings come from three places:

1. **Parallel research** - three research agents finish in the time of one
2. **Parallel implementation** - agents writing to different files simultaneously
3. **Parallel verification** - tests, linting, and review all running at once

The compounding effect is significant. Over a week of feature development, you ship 2-3x more than sequential workflows. Over a month, the velocity difference is dramatic.

The investment is modest: a few markdown files for sub-agents, some discipline around file ownership in parallel tasks, and CLAUDE.md rules that keep everything consistent. Once the patterns are in place, every project benefits from them.

Start with the Task tool and explicit parallel prompts. Add custom sub-agents as you identify recurring specialist roles. Graduate to worktrees when you are building multiple features simultaneously. Each layer adds throughput without adding complexity to any individual agent's job.

## Frequently Asked Questions

### How do I make Claude Code run tasks in parallel?

Use explicit parallel instructions in your prompt. Phrases like "in parallel," "simultaneously," or "fan out" trigger the Task tool. Number your tasks and state that they are independent. For example: "These tasks are independent and can run simultaneously: 1. Research X, 2. Scaffold Y, 3. Write tests for Z." Avoid words like "then" which imply sequential dependencies.

### What is the maximum number of parallel agents Claude Code can spawn?

Claude Code can spawn up to 7 Task agents simultaneously within a single session. For more parallelism, use git worktrees to run multiple independent Claude Code sessions, each on its own branch with full session isolation.

### How do I create a custom sub-agent in Claude Code?

Create a markdown file in `.claude/agents/` with YAML frontmatter specifying the agent name, description, and allowed tools. The body of the file defines the agent's behavior, rules, and output format. For example, `.claude/agents/researcher.md` could define a research specialist with WebSearch and Read tools but no Write access. Type `/agents` in Claude Code to create agents interactively.

### What is the difference between Task agents and worktrees?

Task agents run within a single Claude Code session and share the same git branch. They are best for subtasks that take seconds to minutes and need shared context. Worktrees are completely independent Claude Code sessions on separate git branches - best for features taking 30+ minutes that are fully independent. Worktrees provide full isolation but require manual branch merging afterward.

### How do I prevent parallel agents from conflicting?

Assign each agent to different files or directories. Never have two agents modify the same file simultaneously. Define file ownership rules in your CLAUDE.md - for example, one agent owns `src/db/`, another owns `src/api/`, another owns `src/components/`. If two features must touch the same file, make them sequential rather than parallel.

### What is the scout-build-verify pattern?

A three-phase development pattern that maximizes parallelism. Phase 1 (Scout): run parallel research agents to understand the codebase, APIs, and requirements without modifying anything. Phase 2 (Build): run parallel implementation agents writing to different files based on scout findings. Phase 3 (Verify): run parallel testing, linting, and review agents to validate all changes. Repeat the cycle for iterative refinement.

### How do sub-agents share context with the main session?

They do not share context automatically. Each Task agent has its own context window. If an agent needs information the orchestrator found, include it explicitly in the task prompt. For persistent shared context, use CLAUDE.md as the "contract" that every agent reads - put coordination rules, style guides, and conventions there.

### Can I use multi-agent workflows in any project?

Yes. The Task tool is available by default in Claude Code. Custom sub-agents require creating markdown files in `.claude/agents/`. Worktrees require git. The patterns work best in projects with clear file boundaries where different features touch different parts of the codebase. Projects with heavily shared files benefit less from parallelism.

## Further reading

- [Seven AI Agent Orchestration Patterns](/blog/seven-ai-agent-orchestration-patterns)
- [The Agent Reliability Cliff](/blog/the-agent-reliability-cliff)


Building SaaS with AI Agents in 2026: The Complete Workflow
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
Building a SaaS product used to take a team of three to five engineers several months to reach launch. In 2026, a single developer with [AI agents](/blog/ai-agents-explained) can ship a production-ready SaaS in days to weeks. This is not hyperbole. It is the documented reality of how products are being built right now.

But the gap between "can ship in days" and "does ship in days" is entirely about workflow. Developers who use AI agents like faster typing assistants get incremental speedups. Developers who restructure their entire workflow around agent capabilities get 10x to 50x improvements.

This is the complete workflow for building a SaaS product with AI agents, from the first idea to the first paying customer.

## Phase 1: Planning with AI

The planning phase is where most AI-assisted builds either succeed or fail, and most developers skip it entirely. They open their terminal, start prompting, and let the agent figure it out. This produces working code that goes in the wrong direction.

For the implementation path around this, pair it with [Claude Code Agent Teams, Subagents, and MCP: The 2026 Playbook](/blog/claude-code-agent-teams-subagents-2026) and [Why Skills Beat Prompts for Coding Agents in 2026](/blog/why-skills-beat-prompts-for-coding-agents-2026); those guides connect the idea to a shippable TypeScript stack.

### Writing the PRD

Before touching code, write a Product Requirements Document. This is not a 40-page enterprise document. It is 1 to 2 pages that answer five questions:

1. **What is the product?** One sentence. "A cron job monitoring service that sends alerts when jobs fail."
2. **Who is the user?** One sentence. "Developers running scheduled tasks in production."
3. **What are the core features?** Numbered list of 5 to 8 features, prioritized.
4. **What is the tech stack?** Specific choices with reasons.
5. **What does the data model look like?** Tables, relationships, key fields.

The PRD serves two audiences: you (for clarity) and the AI agent (for context). When you start coding, the PRD becomes part of your project context. The agent reads it and understands what it is building and why.

```markdown
# CronWatch PRD

Cron job monitoring SaaS. Developers add their cron jobs, set alert
rules, and get notified when jobs fail, run late, or produce errors.

## Users
Developers and DevOps engineers running scheduled tasks in production.

## Core Features (Priority Order)
1. Dashboard showing all monitored cron jobs with status
2. Webhook endpoint that cron jobs ping on start/complete/fail
3. Alert rules: email and Slack when job fails or misses window
4. Run history with logs and duration tracking
5. Team support: invite members, share dashboards
6. Pricing: Starter ($9, 10 jobs), Pro ($29, 50 jobs), Business ($79, unlimited)

## Stack
- Next.js 16 (App Router, Server Components)
- Neon (Postgres via Drizzle ORM)
- Clerk (auth, organizations)
- Tailwind (styling)
- Deployed on Coolify (Hetzner VPS)

## Data Model
- users: id, clerkId, email, plan, createdAt
- cronJobs: id, userId, name, schedule, webhookUrl, status, lastPingAt
- cronRuns: id, jobId, startedAt, completedAt, status, logs
- alerts: id, jobId, type, channel, config
```

This PRD is 30 lines. It took 15 minutes to write. It will save hours of misdirected agent work because every coding session starts with the agent knowing exactly what it is building.

### Decomposing into Iterations

Do not give the agent the entire PRD and say "build this." That is the equivalent of handing a new hire a 50-page spec on their first day. Instead, decompose the PRD into iterations of 2 to 4 features each.

```
Iteration 1: Foundation
- Project scaffold (Next.js + Clerk + Neon + Drizzle)
- Database schema for users, cronJobs, cronRuns
- Auth flow: sign up, sign in, dashboard shell
- Basic dashboard showing empty state

Iteration 2: Core Feature
- Webhook endpoint for cron job pings
- Job status tracking (healthy, late, failed)
- Run history table with logs
- Dashboard populated with real data

Iteration 3: Alerts
- Alert rules configuration UI
- Email notification system
- Slack webhook integration
- Alert history and acknowledgment

Iteration 4: Billing and Launch
- Stripe integration via Autumn credits
- Pricing page with plan comparison
- Plan-gated feature limits
- Landing page, deploy, go live
```

Each iteration is a self-contained unit of work that produces a deployable increment. The agent can complete an iteration in a focused session. You review, adjust, and move to the next iteration.

## Phase 2: Scaffolding

Scaffolding is the phase where AI agents provide the most dramatic speedup. What takes a developer 2 to 4 hours of manual setup takes an agent 5 minutes.

### The Scaffold Prompt

```
Read the PRD in CLAUDE.md. Set up Iteration 1:

1. Initialize Next.js 16 with TypeScript, Tailwind, App Router
2. Install and configure Clerk (auth provider)
3. Install and configure Drizzle ORM with Neon Postgres
4. Create the database schema from the PRD data model
5. Set up the project structure:
   - src/db/schema.ts (Drizzle schema)
   - src/db/queries/ (query functions)
   - src/actions/ (server actions)
   - src/components/ (React components)
6. Create a basic authenticated dashboard shell
7. Push the schema to the database
8. Commit with message "scaffold: next.js + clerk + neon + drizzle"
```

The agent handles dependency installation, configuration file creation, environment variable setup, schema definition, and the initial page structure. The output is a working, authenticated application with a database connection.

### What to Watch During Scaffolding

Even with a clear prompt, scaffolding can go wrong. Watch for these:

**Dependency version conflicts.** AI agents sometimes install incompatible package versions. Review the package.json before moving on. Run the dev server and verify it starts cleanly.

**Auth configuration gaps.** Clerk needs environment variables, middleware configuration, and provider wrapping. Verify the full auth flow works: sign up, sign in, redirect to dashboard, sign out.

**Database connection.** Push the schema and verify tables exist. Run a simple query to confirm the connection works through the ORM.

**Type safety.** Check that TypeScript strict mode is enabled and that the schema types propagate to queries and server actions. Type errors caught here prevent cascading issues later.

The scaffold phase should end with a running application that you can sign into and see an empty dashboard. If it does not run, fix it before proceeding. Technical debt compounds faster with AI agents because they build on top of whatever exists.

## Phase 3: Parallel Development

This is where the workflow diverges from traditional development. Instead of building features sequentially, you build them in parallel using multiple agent sessions.

### The Parallel Pattern

Identify features within an iteration that have no dependencies on each other. Assign each to a separate agent session or worktree.

For Iteration 2 of CronWatch:

```
Agent 1 (worktree: feature/webhook-endpoint):
  Build the webhook endpoint for cron job pings.
  - POST /api/webhook/:jobId with start/complete/fail events
  - Update job status and create cronRun records
  - Handle duplicate pings and out-of-order events

Agent 2 (worktree: feature/run-history):
  Build the run history table component.
  - Query cronRuns for a given job
  - Display start time, duration, status, truncated logs
  - Pagination for jobs with many runs
  - Empty state for jobs with no runs yet

Agent 3 (worktree: feature/dashboard-populated):
  Populate the dashboard with real job data.
  - Query all cronJobs for the authenticated user
  - Display status badges (healthy/late/failed)
  - Last ping timestamp and next expected ping
  - Quick actions: pause, delete, view history
```

Each agent works in its own Git worktree, making changes that do not conflict with the others. When all three finish, you merge the worktrees in sequence, resolving any conflicts.

### Why Parallel Works

Sequential development has a fundamental bottleneck: the developer's context window. You can only think about one feature at a time. While you build the webhook endpoint, the dashboard and run history are blocked.

Parallel agent development removes this bottleneck. Three features that would take three sequential days take one parallel day. The developer's job shifts from writing code to reviewing and integrating code.

The constraint on parallelism is dependency. Features that depend on each other's output cannot run in parallel. The webhook endpoint must exist before the dashboard can display real data. But within a dependency layer, everything is parallelizable.

### Managing Worktrees

Git worktrees are the mechanism that makes parallel development practical. Each worktree is a separate checkout of the same repository, allowing multiple branches to be active simultaneously.

```bash
# Create worktrees for parallel features
git worktree add ../cronwatch-webhook feature/webhook-endpoint
git worktree add ../cronwatch-history feature/run-history
git worktree add ../cronwatch-dashboard feature/dashboard-populated

# Run agents in each worktree
cd ../cronwatch-webhook && claude
cd ../cronwatch-history && claude
cd ../cronwatch-dashboard && claude
```

When agents complete their work:

```bash
# Merge back to main
git checkout main
git merge feature/webhook-endpoint
git merge feature/run-history
git merge feature/dashboard-populated

# Clean up worktrees
git worktree remove ../cronwatch-webhook
git worktree remove ../cronwatch-history
git worktree remove ../cronwatch-dashboard
```

The key discipline is keeping features genuinely independent within a parallel batch. If Agent 2 needs to import a type that Agent 1 is creating, they are not independent. Move the shared type to the base branch before starting the parallel batch.

## Phase 4: The Build Loop

Within each feature (whether parallel or sequential), the agent follows a consistent build loop.

### Step 1: Plan

Start every feature with a plan prompt. The agent reads the project context, understands the current state of the codebase, and outlines its approach before writing code.

```
Plan the webhook endpoint feature. Read the schema, understand the
existing patterns in src/actions/ and src/db/queries/, and outline:
1. What files to create or modify
2. What the API contract looks like
3. How you'll handle edge cases (duplicate pings, invalid jobId)
4. What tests you'll write
```

Review the plan before approving execution. This is your highest-leverage intervention point. Catching an architectural mistake at the planning stage [costs](/blog/ai-coding-tools-pricing-comparison) 30 seconds. Catching it after implementation costs an hour.

### Step 2: Implement

Approve the plan and let the agent implement. For most features, this is hands-off. The agent creates files, writes code, and makes incremental progress.

Watch the terminal output but do not interrupt unless the agent is going clearly wrong. Frequent interruptions break the agent's multi-step reasoning chain and produce worse results than letting it complete and then correcting.

### Step 3: Verify

After implementation, verify the feature works.

```
Run the dev server. Navigate to the webhook endpoint.
Send a test POST request with curl:
  curl -X POST http://localhost:3000/api/webhook/test-job-id \
    -H "Content-Type: application/json" \
    -d '{"event": "complete", "duration": 1234}'
Verify the response and check the database for the new cronRun record.
```

Automated verification is better than manual verification. If the agent wrote tests, run them. If it did not, have it write tests before moving on.

### Step 4: Review

Read the code the agent wrote. Not every line, but the important parts: data access patterns, error handling, security boundaries, and type definitions.

AI-generated code has consistent failure patterns:
- Missing error handling for edge cases
- Overly permissive type definitions (using `any`)
- Missing authorization checks on API routes
- Hardcoded values that should be configuration
- Missing input validation on user-facing endpoints

These are the things to look for during review. The structural code (routing, component layout, query construction) is usually correct.

### Step 5: Commit

Commit after every feature. Do not batch multiple features into one commit. Atomic commits make it possible to revert a single feature without losing others.

```
Commit this feature with message:
"add webhook endpoint for cron job pings"
```

## Phase 5: Testing

Testing in an AI-agent workflow is different from traditional testing because the agent can both write and run tests.

### The Testing Prompt

```
Write tests for the webhook endpoint:
1. Happy path: valid ping creates a cronRun record
2. Invalid jobId returns 404
3. Duplicate ping within 1 second is idempotent
4. Missing event field returns 400
5. Unauthorized request returns 401

Use vitest. Mock the database layer. Run the tests and fix any failures.
```

The agent writes the tests, runs them, sees failures, and fixes them. This test-write-fix loop is one of the strongest applications of AI agents because the feedback loop is immediate and unambiguous. The test either passes or it does not.

### Integration Testing

Unit tests verify individual functions. Integration tests verify that the system works end to end. Have the agent write integration tests that exercise the full stack:

```
Write an integration test that:
1. Creates a test user via Clerk test helpers
2. Creates a cron job via the API
3. Sends a webhook ping
4. Verifies the dashboard shows the updated status
5. Cleans up test data
```

Integration tests are harder for agents to write correctly because they depend on external services (database, auth provider). Provide explicit instructions about how to set up test fixtures and mock external dependencies.

### The Testing Gap

AI agents are better at writing tests than most developers assume. They are worse at knowing which tests matter. An agent will happily write 50 unit tests for a utility function and zero tests for the authorization logic that protects user data.

Your job as the developer is to direct testing effort toward the highest-risk code. Security boundaries, payment processing, data mutations, and authorization checks need thorough tests. Rendering logic and formatting utilities need minimal tests.

## Phase 6: Billing and Monetization

Billing is the phase where most AI-built projects stall. The agent can scaffold Stripe integration, but the business logic around plans, limits, and upgrades requires careful specification.

### The Billing Spec

```
Implement Stripe billing via Autumn SDK:

Plans:
- Starter ($9/mo): 10 monitored jobs, email alerts only
- Pro ($29/mo): 50 monitored jobs, email + Slack alerts
- Business ($79/mo): Unlimited jobs, all alert channels, priority support

Implementation:
1. Pricing page at /pricing with plan comparison
2. Checkout flow: pricing -> Stripe checkout -> redirect to dashboard
3. Plan enforcement: check user's plan before creating jobs
4. Upgrade/downgrade flow in account settings
5. Middleware: redirect unauthenticated users to /pricing, not /dashboard
6. Owner bypass: my account (isOwner flag) skips all billing checks
```

The specification must be explicit about enforcement. "Check user's plan before creating jobs" tells the agent to add authorization logic. Without this, the agent builds a pricing page that looks correct but does not actually gate features. The same problem shows up in [AI coding tools pricing](/blog/ai-coding-tools-pricing-2026): sticker price means less than the limits behind it.

### Plan Gating

The most common mistake in AI-built billing systems is decorative pricing. The pricing page exists. The checkout flow works. But the application does not actually enforce limits. Users on the free tier can access pro features because no middleware checks their subscription status.

Verify plan gating explicitly:

```
Test plan gating:
1. Sign in as a Starter user
2. Try to create an 11th cron job
3. Verify the app shows an upgrade prompt, not a success message
4. Try to add a Slack alert
5. Verify the app shows "Pro plan required"
```

If the agent did not implement enforcement, it will fail these tests. Fix it before launch.

## Phase 7: Deployment

Deployment is the easiest phase to automate and the one where most developers waste the most time.

### The Deploy Checklist

```
Deploy to production:

1. Environment variables:
   - Verify all env vars are set in Coolify/Vercel
   - DATABASE_URL, CLERK_SECRET_KEY, STRIPE_SECRET_KEY, etc.

2. Database:
   - Run migrations against production database
   - Verify schema matches local

3. Build:
   - Run production build locally first: npm run build
   - Fix any build errors before pushing

4. DNS:
   - Add A record pointing to server IP
   - Add CNAME for www subdomain
   - Wait for propagation (usually < 5 minutes with Cloudflare)

5. Push:
   - git push origin main
   - Monitor build logs in Coolify
   - Verify deployment at production URL

6. Smoke test:
   - Sign up flow
   - Create a cron job
   - Send a webhook ping
   - Verify alert delivery
```

The agent can execute most of this checklist autonomously. The developer verifies the smoke tests and handles any DNS issues that arise.

### Post-Deploy Monitoring

The first 24 hours after deployment are critical. Set up basic monitoring:

```
Add a health endpoint at /api/health that checks:
1. Database connection (run a simple query)
2. Clerk auth service availability
3. Response time under 200ms

Add error tracking via a simple error boundary that logs
to the server. We'll add proper monitoring later.
```

Start simple. A health endpoint that returns 200 or 500 is enough for launch. Add Sentry, DataDog, or equivalent later when you have users generating real traffic.

## Phase 8: Iteration After Launch

Launching is not the end. It is the beginning of the feedback loop that actually matters.

### User Feedback Loop

The first real users will find issues that no amount of testing catches. The workflow for handling feedback with AI agents:

1. User reports an issue
2. Create a GitHub issue with reproduction steps
3. Assign the issue to an agent session
4. Agent reads the issue, reproduces it, fixes it, writes a test
5. You review the fix and merge
6. Deploy

This loop can turn around bug fixes in minutes instead of hours. The agent handles the tedious parts (reproduction, investigation, fix implementation) while you handle the judgment parts (is this the right fix, does it introduce regressions, should we prioritize this).

### Feature Requests

New features follow the same pattern as the initial build. Write a spec, decompose into tasks, execute with agents, review, deploy. Each iteration builds on the foundation that previous iterations created.

The key advantage of AI-assisted iteration is speed. A feature that would take a traditional sprint (two weeks) can ship in a day. This speed means you can respond to user feedback faster, which means users see their requests implemented quickly, which means higher retention.

## Common Failure Modes

### Failure 1: No Project Context

Starting an agent session without CLAUDE.md, without a PRD, without architecture documentation. The agent guesses at conventions and makes decisions you would not make. Every session requires corrections that compound into technical debt.

**Fix:** Invest 30 minutes in project context before writing any code. Update the context as the project evolves. Our [README generator](/readme-generator) is a quick way to bootstrap that first context file from a folder of code.

### Failure 2: No Review

Trusting agent output without reading it. The agent writes correct-looking code that has subtle bugs: missing auth checks, race conditions, unhandled edge cases. These ship to production and become user-facing bugs.

**Fix:** Review every feature before merging. Focus on security boundaries, data mutations, and error handling.

### Failure 3: Monolithic Prompts

Giving the agent a 500-word prompt that describes an entire feature with all its edge cases. The agent loses track of requirements in the middle and produces incomplete implementations.

**Fix:** Decompose complex features into sequential steps. Each prompt should describe one clear unit of work.

### Failure 4: Ignoring Tests

Shipping features without tests because the agent did not write them automatically. When the next iteration modifies shared code, existing features break silently.

**Fix:** Make tests part of every feature prompt. "Implement X and write tests for Y" should be the standard format.

### Failure 5: Premature Optimization

Asking the agent to build performance optimizations, caching layers, and scaling infrastructure before you have users. This wastes time on problems that do not exist yet.

**Fix:** Launch with the simplest implementation that works. Optimize when monitoring shows you where the bottlenecks actually are.

## The Economics

A SaaS product that took a 4-person team three months to build now takes one developer with AI agents two to four weeks. The cost breakdown:

| Item | Traditional | AI-Assisted |
|------|------------|-------------|
| Developer salaries (3 months) | $60,000 to $150,000 | $10,000 to $25,000 (1 developer) |
| AI tooling | $0 | $200 to $400/month |
| Infrastructure | $100 to $500/month | $50 to $200/month |
| Time to first revenue | 3 to 6 months | 2 to 4 weeks |

The math is not close. AI-assisted development does not just reduce cost. It compresses the time to revenue, which changes the economics of what is worth building. Products that were not viable with a three-month development cycle become viable with a two-week cycle.

This is not a future state. This is how SaaS products are being built and shipped today. The workflow is learnable, the tools are available, and the only barrier is adopting a new way of working.

## Frequently Asked Questions

### How long does it take to build a SaaS with AI agents?

A production-ready SaaS can ship in two to four weeks with AI agents, compared to three to six months with a traditional team. The timeline depends on feature complexity, your familiarity with the workflow, and how well you define requirements upfront. Simple MVPs with auth, database, and core feature can ship in under a week. Complex products with billing, team features, and integrations take closer to the four-week mark.

### Which AI tool is best for building a SaaS?

[Claude Code](/blog/what-is-claude-code) is the best primary tool for SaaS development. Its terminal-based agent reads your entire codebase, executes multi-step tasks autonomously, and works with your existing git workflow. Pair it with [Cursor](/tools/cursor) for fast UI iteration. Use [v0](/tools/v0) for rapid component scaffolding. The combination of Claude Code for backend and complex logic plus Cursor for frontend iteration covers the full stack.

### What should I include in a PRD for AI development?

A PRD for AI-assisted development needs five sections: what the product is (one sentence), who the user is (one sentence), core features (5-8 items, prioritized), tech stack (specific choices with reasons), and data model (tables, relationships, key fields). Keep it to 1-2 pages. The PRD becomes part of your project context so the agent understands what it is building and why.

### How do parallel worktrees speed up development?

Git worktrees let you have multiple branches checked out simultaneously in separate directories. You can run multiple AI agents in parallel, each working on an independent feature in its own worktree. Three features that would take three sequential days take one parallel day. When agents complete their work, you merge the worktrees back to main. The constraint is dependency - features that depend on each other cannot run in parallel.

### What are the common failure modes when building with AI?

Five patterns cause most failures. No project context: starting without CLAUDE.md or a PRD means the agent guesses at conventions. No review: trusting agent output without reading security boundaries and error handling. Monolithic prompts: giving 500-word prompts causes the agent to lose track of requirements. Ignoring tests: shipping without tests means the next iteration breaks existing features. Premature optimization: building scaling infrastructure before you have users.

### How do I handle billing with AI-generated code?

Be explicit about enforcement in your prompts. Specify plans, limits, and upgrade flows. After the agent implements billing, verify plan gating explicitly by testing that users on lower tiers cannot access higher-tier features. The most common mistake is decorative pricing where the pricing page exists but the app does not actually enforce limits. Always test the enforcement before launch.

### Can AI agents write production-quality code?

Yes, with appropriate review. AI agents regularly produce code that ships to production. Quality depends on your prompts, your test coverage, and your review process. Focus review on security boundaries, data mutations, error handling, and authorization checks. The structural code (routing, component layout, query construction) is usually correct. AI-generated code has consistent failure patterns you learn to spot and fix.

### What is the build loop for AI-assisted development?

Five steps per feature. Plan: have the agent outline its approach before writing code. Implement: approve the plan and let it run without interruption. Verify: run the dev server and test the feature works. Review: read the important parts of the code (security, data access, error handling). Commit: atomic commits per feature for easy rollback. Repeat this loop for every feature, whether sequential or parallel.


Context Engineering: The Highest-Leverage Skill in AI-Assisted Development
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
Prompt engineering had its moment. It was the skill of 2023. Craft the right question, get a better answer. But prompt engineering addresses a single interaction. You write a prompt, the model responds, and the context evaporates. Every new session starts cold.

Context engineering is what replaced it. Instead of optimizing individual prompts, you design the persistent information architecture that surrounds every AI interaction. The CLAUDE.md file that loads at session start. The skill library that gives your agent specialized capabilities. The memory system that accumulates knowledge across sessions. The system prompt that defines behavior before the first message is sent. For the older prompt-centric pattern this replaces, see the [prompt engineering for coding](/blog/prompt-engineering-for-coding) guide.

This is the highest-leverage skill in AI-assisted development because it compounds. A well-engineered context makes every interaction better. A poorly engineered one makes every interaction worse, and most developers never realize the gap exists. The same compounding logic shows up in [why skills beat prompts](/blog/why-skills-beat-prompts-for-coding-agents-2026) and [continual learning in Claude Code](/blog/continual-learning-claude-code).

## What Context Engineering Actually Is

Context engineering is the practice of designing, structuring, and maintaining the information that an [AI agent](/blog/ai-agents-explained) consumes before and during a task. It covers four layers:

**Layer 1: System prompts.** The foundational instructions that define how the agent behaves. What it should do, what it should never do, how it should format responses, what tools it can use.

**Layer 2: Project context.** The persistent knowledge about your specific codebase, architecture, conventions, and constraints. This is where CLAUDE.md files and similar configuration live.

**Layer 3: Skill libraries.** Reusable, composable instructions for specific tasks. Writing a blog post. Deploying to production. Running a QA audit. Each skill encapsulates domain knowledge that would otherwise need to be re-explained every session.

**Layer 4: Memory systems.** The mechanisms for accumulating and retrieving knowledge across sessions. What the agent learned last time. What decisions were made. What failed and why.

Most developers interact with Layer 1 (system prompts) and stop there. The compounding advantage comes from investing in all four layers.

## The CLAUDE.md File: Your Project's Operating Manual

CLAUDE.md is the most impactful single file you can create in any project. It loads automatically at the start of every Claude Code session, giving the agent immediate awareness of your project's architecture, conventions, and constraints. For a tactical template, use the [complete CLAUDE.md guide](/blog/how-to-write-claudemd-the-complete-guide) alongside this higher-level context model.

Here is what a bad CLAUDE.md looks like:

```markdown
# My Project

This is a Next.js app with Tailwind and Prisma.
Use TypeScript. Follow best practices.
```

This tells the agent almost nothing useful. "Follow best practices" is the context engineering equivalent of telling a new hire to "do good work." It provides no actionable constraints.

Here is what a good CLAUDE.md looks like:

```markdown
# ProjectName

Next.js 16 app with App Router. Neon (Postgres) via Drizzle ORM.
Clerk for auth. Tailwind with custom design tokens.
Deployed on Coolify (Hetzner VPS).

## Critical Rules

- Never use em dashes in any content or code comments
- No emojis anywhere in the codebase
- All API routes must check auth via `auth()` from @clerk/nextjs/server
- Database migrations go through `drizzle-kit push` only, never raw SQL

## Architecture

| Layer | Tech | Notes |
|-------|------|-------|
| Framework | Next.js 16 | App Router, Turbopack |
| Database | Neon + Drizzle | Schema in src/db/schema.ts |
| Auth | Clerk | OAuth, org support |
| Payments | Stripe via Autumn | Credits-based billing |
| AI | Kimi k2.5 | OpenAI-compatible client |

## Data Flow

1. User action triggers server action in `src/actions/`
2. Server action validates input with Zod
3. Drizzle query against Neon
4. Revalidate affected paths
5. Client component re-renders via React Server Components

## File Conventions

- Server actions: `src/actions/{domain}.ts`
- DB queries: `src/db/queries/{domain}.ts`
- Components: `src/components/{domain}/`
- Pages: `app/{route}/page.tsx`

## Common Tasks

### Add a new database table
1. Add schema to `src/db/schema.ts`
2. Run `npx drizzle-kit push`
3. Add queries to `src/db/queries/{domain}.ts`
4. Add server actions to `src/actions/{domain}.ts`

### Deploy
Push to main. Coolify auto-deploys via webhook.
```

The difference is specificity. The good CLAUDE.md gives the agent everything it needs to make correct decisions without asking you. Architecture choices, file conventions, deployment process, and critical constraints that would otherwise require multiple rounds of correction.

## The Anatomy of Effective Project Context

After maintaining CLAUDE.md files across dozens of projects, patterns emerge. The most effective project context files share five characteristics.

### 1. Constraints Before Capabilities

Lead with what the agent should never do. Constraints prevent costly mistakes. Capabilities enable efficiency. Both matter, but a constraint violation (pushing to production, deleting data, using a deprecated API) causes more damage than a missed optimization.

```markdown
## Critical Rules

- NEVER push to remote unless explicitly asked
- NEVER modify .env files
- NEVER use the deprecated v1 API endpoints
- All database changes require migration files, not direct schema edits
```

Constraints should be absolute, not aspirational. "Try to keep functions under 50 lines" is a suggestion. "All API responses must include a `requestId` field" is a constraint. The agent can follow constraints. It cannot reliably follow suggestions because there is no clear boundary.

### 2. Architecture as Decision Context

When the agent knows your architecture, it stops proposing alternatives you have already rejected. Without architecture context, every session risks the agent suggesting Prisma when you use Drizzle, or REST endpoints when you use tRPC, or client-side fetching when you use server components.

The most effective format is a combination of a quick-reference table and a data flow description. The table gives the agent the vocabulary. The data flow tells it how pieces connect.

### 3. File Conventions as Navigation

Agents navigate codebases by convention. If your server actions always live in `src/actions/`, the agent finds them immediately. If they are scattered across the codebase with no pattern, the agent wastes tokens searching.

Document where things go. The payoff is immediate because the agent writes new code in the right location on the first attempt instead of requiring corrections.

### 4. Common Tasks as Playbooks

The "Common Tasks" section is the most underrated part of a CLAUDE.md. It encodes the multi-step workflows that you would otherwise explain verbally every time.

"Add a new API endpoint" is not a single action. It involves creating a route file, adding validation, connecting to the database, adding error handling, updating types, and potentially updating the API documentation. Encoding this sequence means the agent executes it correctly without you supervising each step.

### 5. Living Documentation

A CLAUDE.md that is written once and never updated becomes inaccurate, and inaccurate context is worse than no context. The agent trusts what it reads. If the file says you use Prisma but you migrated to Drizzle last month, every database-related suggestion will be wrong.

The best practice is to make updating the CLAUDE.md part of every significant change. Swap databases? Update the CLAUDE.md. Change the deployment process? Update the CLAUDE.md. Adopt a new convention? Update the CLAUDE.md. Some teams add this to their PR checklist.

## System Prompts: The Foundation Layer

System prompts operate below project context. They define the agent's fundamental behavior: how it communicates, what tools it uses, how it handles ambiguity. If CLAUDE.md is the project manual, the system prompt is the agent's personality and operating protocol.

The most common mistake with system prompts is treating them as a dump for every instruction you can think of. Long, rambling system prompts dilute the important instructions with noise. The agent assigns roughly equal weight to everything in the system prompt, so a 5,000-token prompt with 200 tokens of critical instructions means the critical instructions get 4% of the attention.

### Good System Prompt Structure

```
1. Identity and role (2-3 sentences)
2. Critical constraints (numbered list, under 10 items)
3. Output format preferences (code style, response structure)
4. Tool usage instructions (when to use which tool)
5. Error handling behavior (what to do when uncertain)
```

### Bad System Prompt Patterns

**The encyclopedia.** 10,000 tokens covering every possible scenario. The agent cannot prioritize because everything is presented with equal weight.

**The vague directive.** "Be helpful and write clean code." This adds zero information beyond the model's default behavior.

**The contradictory set.** "Always explain your reasoning" combined with "Keep responses concise." These conflict, and the agent picks whichever it encounters last or whichever is more convenient per response.

**The outdated reference.** Instructions that reference deprecated APIs, old file structures, or retired services. The agent follows them faithfully and produces broken code.

The fix for all of these is the same: treat your system prompt as code. Review it. Test it. Refactor it. Version control it.

## Skill Libraries: Composable Expertise

Skills are the composable building blocks of context engineering. Each skill encapsulates the instructions, context, and references needed for a specific task. Instead of re-explaining how to write a blog post every time, you invoke a skill that contains the format, conventions, frontmatter template, and quality standards.

The key design principle for skills is progressive disclosure. The agent should not load every skill into context at session start. It should see a list of available skills (name and one-line description) and load the full definition only when needed.

```markdown
# Skill: deploy

Deploy the application to production.

## Steps

1. Run `npm run build` and verify no errors
2. Run `npm run test` and verify all pass
3. Check git status - all changes must be committed
4. Push to main branch
5. Verify deployment at https://app.example.com
6. Run smoke tests: health endpoint, auth flow, core feature

## Constraints

- Never deploy on Friday after 3 PM
- Never deploy if any test fails
- Always check the build output for warnings about bundle size

## Rollback

If smoke tests fail:
1. `git revert HEAD`
2. Push to main
3. Verify rollback deployment
4. Open an issue describing the failure
```

This skill is self-contained. Any agent that reads it can execute the deployment process without additional context. The constraints prevent common mistakes. The rollback procedure handles failures.

### Skill Composition

The real power emerges when skills compose. A "ship feature" meta-skill might invoke:

1. The "test" skill to verify the codebase is clean
2. The "deploy" skill to push to production
3. The "monitor" skill to watch for errors post-deploy
4. The "document" skill to update the changelog

Each component skill is independently useful and independently testable. The meta-skill orchestrates them into a workflow. This is the same composition pattern that makes Unix pipes powerful: small, focused tools chained together.

### Skill Accumulation

The most valuable property of skills is that they accumulate. Every time you solve a problem, you can extract the solution into a skill. Over months, your skill library becomes a comprehensive encoding of your team's knowledge and processes.

A developer who has been context engineering for six months might have 50 to 100 skills covering everything from "set up a new microservice" to "handle a customer escalation" to "write a technical blog post." Each skill represents hours of accumulated knowledge compressed into minutes of agent execution time.

## Memory Systems: Knowledge That Persists

Memory is the mechanism that connects sessions. Without memory, every interaction starts from zero. With memory, the agent carries forward what it learned.

There are three practical memory patterns for context engineering.

### Pattern 1: Append-Only Memory Files

The simplest pattern. A file (often called MEMORY.md) that the agent reads at session start and appends to when it learns something new.

```markdown
# Memory

## Project Decisions
- 2026-03-15: Chose Drizzle over Prisma for type-safe queries
- 2026-03-20: Switched from REST to tRPC for internal APIs
- 2026-04-01: Added rate limiting via Upstash Redis

## Patterns That Work
- Server actions with Zod validation catch 90% of input errors
- Parallel sub-agents for independent test suites cut CI time in half

## Patterns That Failed
- Client-side data fetching caused hydration mismatches with SSR
- Caching tRPC responses broke real-time updates
```

The append-only constraint is important. It prevents the agent from overwriting historical context. You can prune the file periodically, but the agent should only add, never delete.

### Pattern 2: Structured Context Files

For larger projects, a single memory file becomes unwieldy. Structured context splits memory into domain-specific files.

```
.context/
  architecture.md    # System design decisions
  conventions.md     # Coding standards and patterns
  incidents.md       # Past failures and fixes
  dependencies.md    # External service notes
  performance.md     # Optimization history
```

Each file is small enough to load on demand. The agent reads the relevant file based on the current task instead of loading everything.

### Pattern 3: Session Snapshots

When a session ends, capture a snapshot of what was accomplished, what decisions were made, and what remains to be done. This creates a chain of context that spans across sessions.

```markdown
# Session 2026-04-09 14:30

## Completed
- Added user preferences table to schema
- Created settings page with form validation
- Connected preferences to AI prompt generation

## Decisions
- Stored preferences as JSONB instead of separate columns
- Used React Hook Form instead of native form handling

## Next Steps
- Add preference sync across devices
- Write tests for preference-dependent AI prompts
- Update onboarding flow to collect initial preferences
```

The next session reads this snapshot and picks up exactly where the previous one left off. No re-explaining, no context loss, no wasted time re-establishing what happened.

## Good Context vs. Bad Context: Real Examples

### Example 1: Deployment Instructions

**Bad:**
```
Deploy the app when ready.
```

**Good:**
```
## Deploy

1. Verify: `npm run build && npm run test`
2. Commit all changes to main
3. Push: `git push origin main`
4. Coolify auto-deploys via webhook (takes ~3 min)
5. Verify: `curl -s https://app.example.com/api/health`
6. If health check fails, check Coolify logs at https://coolify.example.com
```

The bad version assumes the agent knows your deployment process. The good version eliminates ambiguity.

### Example 2: Code Style

**Bad:**
```
Write clean, maintainable TypeScript.
```

**Good:**
```
## Code Style

- Functions: named exports, async when touching DB or external services
- Error handling: throw typed errors from `src/lib/errors.ts`, never raw strings
- Imports: absolute paths via `@/` alias, never relative beyond one level
- Types: colocate with the module, export from barrel files per domain
- Tests: colocate as `{module}.test.ts`, use vitest, mock external services
```

The bad version is indistinguishable from the model's default behavior. The good version encodes specific conventions that differ from defaults.

### Example 3: Database Operations

**Bad:**
```
We use Postgres. Be careful with migrations.
```

**Good:**
```
## Database (Neon + Drizzle)

Schema: `src/db/schema.ts` (single source of truth)
Migrations: `npx drizzle-kit push` (dev), `npx drizzle-kit generate` (prod)

Rules:
- Never write raw SQL except in Drizzle `sql` template literals
- Always add `NOT NULL` constraints unless the field is genuinely optional
- Always add indexes on foreign keys and frequently filtered columns
- New tables must have `createdAt` and `updatedAt` timestamps
- Enum values: add new values only, never rename or remove existing ones
```

The bad version creates anxiety without actionable guidance. The good version gives the agent concrete rules it can follow mechanically.

## Measuring Context Quality

Context engineering is not a write-once activity. You need to measure whether your context is actually working.

### Signal 1: Correction Frequency

Track how often you correct the agent on the same issue. If you keep saying "use Drizzle, not Prisma," your architecture context is either missing or unclear. Every repeated correction is a context engineering bug.

### Signal 2: First-Attempt Accuracy

When the agent generates code, how often is the first attempt correct? Low first-attempt accuracy means the agent lacks necessary context. High first-attempt accuracy means your context is doing its job.

### Signal 3: Token Efficiency

Good context reduces total token usage by preventing wrong turns. If the agent consistently goes down the wrong path and then backtracks, that is wasted tokens caused by insufficient context. Monitor your token usage trends as you improve your context files.

### Signal 4: Onboarding Speed

Give a new team member (or a fresh agent session with no history) your context files and a task. How quickly do they produce correct output? Fast onboarding means your context is comprehensive. Slow onboarding means gaps exist.

## The Context Engineering Workflow

Here is the daily workflow that makes context engineering compound over time.

**Morning:** Read MEMORY.md and session snapshots. Orient yourself on what happened in the last session. Check if any context files need updates.

**During work:** When you correct the agent, note the correction. Do not just fix the output. Fix the context that caused the wrong output. Add the missing constraint, convention, or instruction to the appropriate context file.

**End of session:** Write a session snapshot. What was accomplished, what was decided, what comes next. Update MEMORY.md with any significant learnings.

**Weekly:** Review your skill library. Are there tasks you performed manually that should be skills? Are existing skills outdated? Prune what is no longer relevant. Add what is missing.

This workflow takes 10 to 15 minutes per day. The return is hours of saved time from reduced corrections, faster agent execution, and knowledge that persists instead of evaporating.

## Why This Is the Highest-Leverage Skill

Context engineering multiplies the effectiveness of everything else. Better prompts help one interaction. Better context helps every interaction. A skill library that took 20 hours to build might save 5 minutes per task across 10 tasks per day for months. The math compounds aggressively.

More importantly, context engineering is durable. Models improve, tools change, but the discipline of designing persistent information architectures transfers across every AI system. The CLAUDE.md you write today teaches you principles that apply to whatever system ships next year.

The developers who will be most productive with AI in 2026 and beyond are not the ones writing the cleverest prompts. They are the ones who have invested in context that makes clever prompts unnecessary. When the agent already knows your architecture, conventions, constraints, and processes, the prompt becomes simple: "Add user preferences to the settings page." The context does the rest.

That is the promise of context engineering. Not better questions, but better defaults. Not smarter prompts, but smarter environments. The context you build today is the leverage you have tomorrow.

## Frequently Asked Questions

### What is context engineering?

Context engineering is the practice of designing, structuring, and maintaining the persistent information that an AI agent consumes before and during a task. Unlike prompt engineering, which optimizes individual interactions, context engineering creates durable information architectures that improve every interaction. It covers four layers: system prompts, project context (like CLAUDE.md files), skill libraries, and memory systems.

### What is a CLAUDE.md file?

A CLAUDE.md file is a project-level configuration file that [Claude Code](/blog/what-is-claude-code-complete-guide-2026) reads automatically at the start of every session. It contains your project's architecture, conventions, constraints, and common workflows. A well-written CLAUDE.md eliminates the need to re-explain your codebase every session and prevents the agent from making decisions that violate your project's rules.

### How do I write a good CLAUDE.md file?

Start with constraints before capabilities - what the agent should never do. Include a clear architecture table showing your tech stack. Document file conventions so the agent knows where to find and place code. Add common task playbooks for multi-step workflows like deployment or adding new features. Keep it updated whenever your project changes. Aim for specificity over vague guidelines like "follow best practices."

### What is the difference between prompt engineering and context engineering?

Prompt engineering optimizes a single interaction - you craft a better question to get a better answer, but the context evaporates when the session ends. Context engineering builds persistent information that improves every interaction. A well-engineered CLAUDE.md file, skill library, and memory system means you can give simple prompts like "add user authentication" and the agent already knows your framework, conventions, and deployment process.

### How do skills work in context engineering?

Skills are reusable, composable instructions for specific tasks. Instead of explaining how to deploy your app every time, you create a deploy skill that contains the exact steps, constraints, and rollback procedures. Skills should use progressive disclosure - the agent sees a list of available skills (name and one-line description) and loads the full definition only when needed. Skills accumulate over time, encoding your team's knowledge into executable instructions.

### What is memory in context engineering?

Memory is the mechanism that connects AI sessions. Without memory, every interaction starts from zero. Three practical patterns exist: append-only memory files (like MEMORY.md) that log decisions and learnings, structured context files split by domain (architecture.md, conventions.md, incidents.md), and session snapshots that capture what was accomplished and what comes next at the end of each session.

### How do I measure context quality?

Track four signals: correction frequency (how often you correct the agent on the same issue), first-attempt accuracy (how often the first code generation is correct), token efficiency (wasted tokens from wrong turns indicate insufficient context), and onboarding speed (how quickly a fresh session produces correct output). Every repeated correction is a context engineering bug that should be fixed.

### Is context engineering worth the time investment?

Yes. The time investment is 10 to 15 minutes per day for the workflow, plus the initial setup of your CLAUDE.md and skill library. The return is hours of saved time from reduced corrections, faster agent execution, and knowledge that persists instead of evaporating. A skill library that took 20 hours to build might save 5 minutes per task across 10 tasks per day for months. The math compounds aggressively.


How to Coordinate Multiple AI Agents: The Definitive Guide for 2026
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
## The Coordination Problem

Building a single [AI agent](/blog/ai-agents-explained) is straightforward. You give it a system prompt, connect some tools, and let it run. But the moment you need two agents to share state, hand off tasks, or merge outputs, everything breaks. The agent that wrote the code has no idea the agent that researched the API found a breaking change. The planner generates a task list the executor cannot parse. The reviewer blocks on output the implementer never produced.

This is the coordination problem, and it is the single biggest bottleneck in production multi-agent systems in 2026. The frameworks have matured. The models are capable. What separates systems that work from systems that collapse is how agents communicate, share context, and resolve conflicts. For the simpler conceptual layer, read [multi-agent systems in TypeScript](/blog/multi-agent-systems) before going deep on framework mechanics.

This guide covers every major coordination pattern in use today, with working code across the six dominant frameworks: CrewAI, LangGraph, AutoGen/AG2, [OpenAI Agents SDK](/blog/openai-agents-sdk-typescript), Google ADK, and Claude Code's native agent system. By the end, you will know which pattern fits your use case and how to implement it without the false starts.

## The Six Coordination Patterns

Every multi-agent system in production uses one or more of these patterns. They are not framework-specific. They are architectural primitives that apply regardless of your toolchain. For the shared vocabulary, start with [7 AI agent orchestration patterns](/blog/seven-ai-agent-orchestration-patterns). If your use case is specifically coding work, pair this with [building multi-agent workflows in Claude Code](/blog/building-multi-agent-workflows-claude-code) and the [Claude Code agent teams playbook](/blog/claude-code-agent-teams-subagents-2026).

### 1. Fan-Out / Fan-In (Parallel Scatter-Gather)

Deploy N agents simultaneously on independent subtasks, then merge their outputs. This is the simplest pattern and often the most effective.

**When to use it:** Research across multiple sources. Auditing different parts of a codebase. Generating alternative implementations. Any task where subtasks have zero dependencies on each other.

**The trap:** Most teams underestimate the merge step. Three agents producing three research summaries is easy. Reconciling contradictory findings, deduplicating information, and producing a coherent final output requires a dedicated aggregator - either another agent or a deterministic merge function. The [agent swarms need receipts](/blog/agent-swarms-need-receipts) post covers the reviewable-output side of this failure mode.

```typescript
// Fan-out / Fan-in with explicit aggregation
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

interface AgentTask {
  name: string;
  prompt: string;
}

async function fanOutFanIn(tasks: AgentTask[], mergePrompt: string) {
  // Fan out: all agents run in parallel
  const results = await Promise.all(
    tasks.map(async (task) => {
      const response = await client.messages.create({
        model: "claude-sonnet-4-5-20250514",
        max_tokens: 4096,
        system: `You are a specialized ${task.name} agent. Be thorough and precise.`,
        messages: [{ role: "user", content: task.prompt }],
      });
      return {
        agent: task.name,
        output: response.content[0].type === "text" ? response.content[0].text : "",
      };
    })
  );

  // Fan in: aggregator merges all outputs
  const mergeInput = results
    .map((r) => `## ${r.agent}\n${r.output}`)
    .join("\n\n---\n\n");

  const merged = await client.messages.create({
    model: "claude-sonnet-4-5-20250514",
    max_tokens: 8192,
    system: "You are a synthesis agent. Merge the following agent outputs into a single coherent result. Resolve contradictions. Remove duplicates. Preserve all unique insights.",
    messages: [{ role: "user", content: `${mergePrompt}\n\n${mergeInput}` }],
  });

  return merged.content[0].type === "text" ? merged.content[0].text : "";
}

// Usage
const result = await fanOutFanIn(
  [
    { name: "docs-researcher", prompt: "Research the latest Next.js 16 App Router changes" },
    { name: "migration-analyst", prompt: "Find breaking changes between Next.js 15 and 16" },
    { name: "community-scanner", prompt: "Find common migration issues reported on GitHub" },
  ],
  "Create a comprehensive Next.js 16 migration guide from these research outputs."
);
```

### 2. Pipeline (Sequential Handoff)

Agent A produces output that becomes Agent B's input. Each stage transforms, refines, or builds on the previous result. The output flows in one direction.

**When to use it:** Code generation followed by review. Research followed by synthesis followed by writing. Any workflow with clear stage dependencies.

**The trap:** Pipelines are fragile. If stage 2 produces malformed output, stage 3 crashes. Every pipeline needs validation between stages - either schema checks or a lightweight validator agent.

```python
# Pipeline with inter-stage validation
from anthropic import Anthropic

client = Anthropic()

def run_pipeline(task: str, stages: list[dict]) -> str:
    current_input = task

    for i, stage in enumerate(stages):
        response = client.messages.create(
            model="claude-sonnet-4-5-20250514",
            max_tokens=stage.get("max_tokens", 4096),
            system=stage["system_prompt"],
            messages=[{"role": "user", "content": current_input}],
        )
        output = response.content[0].text

        # Validate output before passing to next stage
        if "validator" in stage:
            is_valid, error = stage["validator"](output)
            if not is_valid:
                # Retry with error context
                retry_response = client.messages.create(
                    model="claude-sonnet-4-5-20250514",
                    max_tokens=stage.get("max_tokens", 4096),
                    system=stage["system_prompt"],
                    messages=[
                        {"role": "user", "content": current_input},
                        {"role": "assistant", "content": output},
                        {"role": "user", "content": f"Validation failed: {error}. Fix and retry."},
                    ],
                )
                output = retry_response.content[0].text

        current_input = output

    return current_input

# Usage: plan -> implement -> review -> document
result = run_pipeline(
    task="Add rate limiting to the /api/generate endpoint",
    stages=[
        {
            "system_prompt": "You are an architect. Break this into implementation steps with file paths and code changes needed.",
            "validator": lambda x: (True, None) if "##" in x else (False, "Output must contain markdown headers for each step"),
        },
        {
            "system_prompt": "You are a senior developer. Implement each step from the plan. Output complete, working code.",
            "max_tokens": 8192,
        },
        {
            "system_prompt": "You are a code reviewer. Review for bugs, security issues, and edge cases. Output the corrected code with inline comments explaining changes.",
            "max_tokens": 8192,
        },
        {
            "system_prompt": "You are a technical writer. Write clear documentation for this feature: what it does, configuration options, and usage examples.",
        },
    ],
)
```

### 3. Hierarchical Delegation

A supervisor agent receives a complex task, decomposes it, assigns subtasks to specialist agents, monitors progress, and assembles the final result. The supervisor can reassign failed tasks or adjust the plan mid-execution.

**When to use it:** Complex projects with interdependencies. Tasks that require adaptive planning - where the next step depends on what happened in the previous one.

**The trap:** The supervisor becomes a bottleneck if it tries to micromanage. Good hierarchical systems give subordinates autonomy within clear boundaries, only escalating to the supervisor on failures or ambiguous requirements.

```typescript
// Hierarchical delegation with dynamic task assignment
interface SubAgent {
  name: string;
  capabilities: string[];
  systemPrompt: string;
}

interface Task {
  id: string;
  description: string;
  requiredCapabilities: string[];
  dependencies: string[];
  status: "pending" | "running" | "complete" | "failed";
  result?: string;
}

class Supervisor {
  private agents: SubAgent[];
  private tasks: Map = new Map();
  private results: Map = new Map();

  constructor(agents: SubAgent[]) {
    this.agents = agents;
  }

  async decompose(goal: string): Promise {
    const response = await client.messages.create({
      model: "claude-sonnet-4-5-20250514",
      max_tokens: 4096,
      system: `You are a project manager. Decompose goals into tasks.
        Available specialists: ${this.agents.map((a) => `${a.name} (${a.capabilities.join(", ")})`).join("; ")}
        Output JSON: { "tasks": [{ "id": "t1", "description": "...", "requiredCapabilities": ["..."], "dependencies": [] }] }`,
      messages: [{ role: "user", content: goal }],
    });

    const parsed = JSON.parse(response.content[0].type === "text" ? response.content[0].text : "{}");
    return parsed.tasks;
  }

  findBestAgent(task: Task): SubAgent | undefined {
    return this.agents.find((agent) =>
      task.requiredCapabilities.every((cap) => agent.capabilities.includes(cap))
    );
  }

  async execute(goal: string): Promise {
    const tasks = await this.decompose(goal);
    tasks.forEach((t) => this.tasks.set(t.id, { ...t, status: "pending" }));

    while ([...this.tasks.values()].some((t) => t.status === "pending")) {
      // Find tasks whose dependencies are all complete
      const ready = [...this.tasks.values()].filter(
        (t) =>
          t.status === "pending" &&
          t.dependencies.every((dep) => this.tasks.get(dep)?.status === "complete")
      );

      // Execute ready tasks in parallel
      await Promise.all(
        ready.map(async (task) => {
          const agent = this.findBestAgent(task);
          if (!agent) {
            task.status = "failed";
            return;
          }
          task.status = "running";

          // Include dependency results as context
          const context = task.dependencies
            .map((dep) => `Result of ${dep}: ${this.results.get(dep)}`)
            .join("\n");

          const response = await client.messages.create({
            model: "claude-sonnet-4-5-20250514",
            max_tokens: 4096,
            system: agent.systemPrompt,
            messages: [
              {
                role: "user",
                content: `${task.description}\n\nContext from previous tasks:\n${context}`,
              },
            ],
          });

          const result = response.content[0].type === "text" ? response.content[0].text : "";
          this.results.set(task.id, result);
          task.status = "complete";
        })
      );
    }

    return [...this.results.values()].join("\n\n---\n\n");
  }
}
```

### 4. Blackboard (Shared State)

All agents read from and write to a shared state object. No agent directly communicates with another. Instead, they observe the state, decide if they have something to contribute, and write their contribution back. A controller monitors the state and triggers agents when relevant sections change.

**When to use it:** Problems where the solution emerges from multiple perspectives iterating on shared data. Code review cycles. Collaborative document editing. Systems where agents need to react to each other's work without explicit messaging.

**The trap:** Race conditions. Two agents writing to the same state key simultaneously. Use optimistic locking or a queue-based write system.

```typescript
// Blackboard pattern with change-triggered agents
interface BlackboardState {
  [key: string]: {
    value: any;
    lastUpdatedBy: string;
    version: number;
  };
}

type AgentTrigger = {
  agent: SubAgent;
  watchKeys: string[];
  handler: (state: BlackboardState, changedKey: string) => Promise>;
};

class Blackboard {
  private state: BlackboardState = {};
  private triggers: AgentTrigger[] = [];
  private maxIterations: number;

  constructor(maxIterations = 10) {
    this.maxIterations = maxIterations;
  }

  register(trigger: AgentTrigger) {
    this.triggers.push(trigger);
  }

  async write(key: string, value: any, author: string) {
    const current = this.state[key];
    this.state[key] = {
      value,
      lastUpdatedBy: author,
      version: (current?.version ?? 0) + 1,
    };

    // Fire triggers for agents watching this key
    const watchers = this.triggers.filter(
      (t) => t.watchKeys.includes(key) && t.agent.name !== author
    );

    for (const watcher of watchers) {
      const updates = await watcher.handler(this.state, key);
      for (const [k, v] of Object.entries(updates)) {
        await this.write(k, v, watcher.agent.name);
      }
    }
  }

  getState(): BlackboardState {
    return structuredClone(this.state);
  }
}

// Usage: code review cycle
const board = new Blackboard(5);

board.register({
  agent: { name: "implementer", capabilities: ["code"], systemPrompt: "..." },
  watchKeys: ["review_feedback"],
  handler: async (state, changedKey) => {
    // Read feedback, produce revised code
    const feedback = state["review_feedback"].value;
    const currentCode = state["code"].value;
    // ... call LLM to revise code based on feedback
    return { code: revisedCode };
  },
});

board.register({
  agent: { name: "reviewer", capabilities: ["review"], systemPrompt: "..." },
  watchKeys: ["code"],
  handler: async (state, changedKey) => {
    const code = state["code"].value;
    // ... call LLM to review code
    return { review_feedback: feedback };
  },
});
```

### 5. Handoff Chain (Agent-to-Agent Transfer)

One agent works on a task until it hits the boundary of its expertise, then transfers control (and full context) to a more appropriate agent. Unlike pipelines, handoffs are non-linear - Agent A might hand off to B, which hands off to C, which hands back to A.

This is the model that OpenAI Agents SDK and [Claude Code](/blog/what-is-claude-code-complete-guide-2026)'s sub-agent system both use natively.

**When to use it:** Customer support routing. Complex debugging sessions where the problem crosses domains. Any workflow where the right specialist depends on runtime conditions.

```python
# Handoff pattern using OpenAI Agents SDK
from agents import Agent, Runner

# Define specialists
frontend_agent = Agent(
    name="Frontend Specialist",
    instructions="You handle React, CSS, and browser-side issues. Hand off to backend_agent for API or database problems.",
    handoffs=["backend_agent"],
)

backend_agent = Agent(
    name="Backend Specialist",
    instructions="You handle API routes, database queries, and server logic. Hand off to devops_agent for deployment or infrastructure problems.",
    handoffs=["devops_agent"],
)

devops_agent = Agent(
    name="DevOps Specialist",
    instructions="You handle deployment, CI/CD, Docker, and infrastructure. Hand off to frontend_agent if the issue is client-side.",
    handoffs=["frontend_agent"],
)

# Triage agent decides the first specialist
triage_agent = Agent(
    name="Triage",
    instructions="Analyze the issue and hand off to the most appropriate specialist.",
    handoffs=[frontend_agent, backend_agent, devops_agent],
)

# Run - the SDK handles handoff routing automatically
result = await Runner.run(triage_agent, "The /api/users endpoint returns 500 but only in production")
```

### 6. Consensus (Vote and Merge)

Multiple agents independently solve the same problem, then a judge agent evaluates the solutions and selects the best one (or synthesizes elements from multiple solutions). This is the pattern behind "tournament" approaches to code generation and the backbone of LMSYS-style evaluations.

**When to use it:** High-stakes code generation where correctness matters more than speed. Architectural decisions with multiple valid approaches. Any task where you want diversity of solutions before committing.

```typescript
// Consensus pattern: generate, evaluate, select
async function consensus(
  task: string,
  numCandidates: number = 3,
  evaluationCriteria: string
): Promise<{ winner: string; reasoning: string }> {
  // Generate N independent solutions
  const candidates = await Promise.all(
    Array.from({ length: numCandidates }, (_, i) =>
      client.messages.create({
        model: "claude-sonnet-4-5-20250514",
        max_tokens: 4096,
        system: `You are solution generator #${i + 1}. Solve the task independently. Do not hedge - commit to a specific approach.`,
        messages: [{ role: "user", content: task }],
      })
    )
  );

  const solutions = candidates.map((c, i) => ({
    id: i + 1,
    content: c.content[0].type === "text" ? c.content[0].text : "",
  }));

  // Judge evaluates all solutions
  const judgeInput = solutions
    .map((s) => `## Solution ${s.id}\n${s.content}`)
    .join("\n\n---\n\n");

  const judgment = await client.messages.create({
    model: "claude-sonnet-4-5-20250514",
    max_tokens: 4096,
    system: `You are an expert evaluator. Compare the solutions against these criteria: ${evaluationCriteria}. Select the best one or synthesize the strongest elements from multiple solutions. Output JSON: { "winner": "solution content", "reasoning": "why this is best" }`,
    messages: [{ role: "user", content: judgeInput }],
  });

  return JSON.parse(judgment.content[0].type === "text" ? judgment.content[0].text : "{}");
}
```

## Framework Implementation Guide

Each framework implements these patterns with different primitives. Here is how the six major options handle coordination.

### CrewAI: Role-Based Crews

CrewAI (v1.10.1, 45.9K GitHub stars) models agents as team members with roles, goals, and backstories. Coordination happens through Crews (groups of agents executing a set of Tasks) and Flows (event-driven pipelines connecting multiple Crews).

```python
from crewai import Agent, Task, Crew, Process
from crewai.flow.flow import Flow, listen, start

# Define agents with roles
researcher = Agent(
    role="Senior Research Analyst",
    goal="Find comprehensive technical information about the given topic",
    backstory="You are a veteran technical researcher who values accuracy over speed.",
    tools=[web_search, scrape_url],
    verbose=True,
)

writer = Agent(
    role="Technical Writer",
    goal="Transform research into clear, actionable documentation",
    backstory="You write for practitioners who want to build, not theorize.",
    verbose=True,
)

reviewer = Agent(
    role="Technical Editor",
    goal="Ensure accuracy, completeness, and clarity",
    backstory="You have reviewed thousands of technical documents and have zero tolerance for hand-waving.",
    verbose=True,
)

# Define tasks with dependencies
research_task = Task(
    description="Research {topic} comprehensively. Include version numbers, code examples, and known limitations.",
    expected_output="A structured research report with sections, code blocks, and source citations.",
    agent=researcher,
)

writing_task = Task(
    description="Write a technical guide based on the research. Target audience: senior developers.",
    expected_output="A 2000+ word guide with introduction, sections, code examples, and conclusion.",
    agent=writer,
    context=[research_task],  # Receives research output as context
)

review_task = Task(
    description="Review the guide for technical accuracy, completeness, and readability.",
    expected_output="Reviewed guide with corrections applied and editor notes.",
    agent=reviewer,
    context=[writing_task],
)

# Assemble and run
crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, writing_task, review_task],
    process=Process.sequential,  # or Process.hierarchical with a manager
    memory=True,  # Enable shared memory across agents
    planning=True,  # Enable planning agent for step-by-step execution
)

result = crew.kickoff(inputs={"topic": "WebSocket authentication patterns"})
```

**CrewAI Flows** connect multiple Crews into larger workflows with conditional routing:

```python
class ContentPipeline(Flow):
    @start()
    def research_phase(self):
        research_crew = Crew(agents=[researcher], tasks=[research_task])
        self.state["research"] = research_crew.kickoff()

    @listen(research_phase)
    def writing_phase(self):
        if len(self.state["research"].raw) < 500:
            # Not enough research - send back for more
            return self.research_phase()
        writing_crew = Crew(agents=[writer], tasks=[writing_task])
        self.state["draft"] = writing_crew.kickoff()

    @listen(writing_phase)
    def review_phase(self):
        review_crew = Crew(agents=[reviewer], tasks=[review_task])
        self.state["final"] = review_crew.kickoff()

pipeline = ContentPipeline()
result = pipeline.kickoff()
```

### LangGraph: State Machines

LangGraph (v1.1.6, 126K GitHub stars) models agent coordination as a directed graph with typed state. Nodes are functions. Edges are transitions. State is the communication channel.

```python
from langgraph.graph import StateGraph, START, END
from langgraph.prebuilt import create_react_agent
from typing import TypedDict, Annotated
from operator import add

class AgentState(TypedDict):
    task: str
    research: Annotated[list[str], add]
    code: str
    review: str
    final_output: str

def research_node(state: AgentState) -> dict:
    # Agent researches the task
    result = research_agent.invoke({"messages": [{"role": "user", "content": state["task"]}]})
    return {"research": [result["messages"][-1].content]}

def code_node(state: AgentState) -> dict:
    context = "\n".join(state["research"])
    result = code_agent.invoke({
        "messages": [{"role": "user", "content": f"Task: {state['task']}\nResearch: {context}"}]
    })
    return {"code": result["messages"][-1].content}

def review_node(state: AgentState) -> dict:
    result = review_agent.invoke({
        "messages": [{"role": "user", "content": f"Review this code:\n{state['code']}"}]
    })
    return {"review": result["messages"][-1].content}

def should_revise(state: AgentState) -> str:
    if "APPROVED" in state["review"]:
        return "finalize"
    return "code"  # Loop back for revision

# Build the graph
graph = StateGraph(AgentState)
graph.add_node("research", research_node)
graph.add_node("code", code_node)
graph.add_node("review", review_node)
graph.add_node("finalize", lambda s: {"final_output": s["code"]})

graph.add_edge(START, "research")
graph.add_edge("research", "code")
graph.add_edge("code", "review")
graph.add_conditional_edges("review", should_revise, {"finalize": "finalize", "code": "code"})
graph.add_edge("finalize", END)

app = graph.compile()
result = app.invoke({"task": "Build a rate limiter middleware for Express"})
```

LangGraph's strength is the explicit control flow. You can see exactly where agents loop, branch, and converge. The state machine is debuggable, serializable, and supports human-in-the-loop interruptions at any node.

### AutoGen / AG2: Conversation-Based

AG2 (formerly AutoGen, with community governance from Meta, IBM, and university researchers) models multi-agent coordination as conversations. Agents send messages to each other, and the framework manages turn-taking, termination conditions, and group dynamics.

```python
from autogen import ConversableAgent, GroupChat, GroupChatManager

# Define conversational agents
planner = ConversableAgent(
    name="Planner",
    system_message="You break down complex tasks into actionable steps. Output numbered lists.",
    llm_config={"model": "claude-sonnet-4-5-20250514"},
)

coder = ConversableAgent(
    name="Coder",
    system_message="You write production-quality TypeScript. Always include error handling and types.",
    llm_config={"model": "claude-sonnet-4-5-20250514"},
)

critic = ConversableAgent(
    name="Critic",
    system_message="You review code for bugs, performance, and security. Be specific about issues.",
    llm_config={"model": "claude-sonnet-4-5-20250514"},
)

# Group chat with automatic speaker selection
group_chat = GroupChat(
    agents=[planner, coder, critic],
    messages=[],
    max_round=12,
    speaker_selection_method="auto",  # LLM decides who speaks next
)

manager = GroupChatManager(groupchat=group_chat)

# Kick off the conversation
planner.initiate_chat(
    manager,
    message="We need to add WebSocket support to our Express API with JWT authentication.",
)
```

AG2's MemoryStream architecture (introduced in the 2026 beta) makes every conversation event-driven and replayable. You can step through execution event by event for debugging, pause for human review, and resume.

### Google ADK: Hierarchical Agent Trees

Google's Agent Development Kit (ADK) models coordination as a hierarchy. A root agent delegates to child agents, which can have their own children. The framework handles routing, context passing, and result aggregation.

```python
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

# Leaf agents - specialists
research_agent = Agent(
    name="researcher",
    model="gemini-2.5-flash",
    instruction="Research the given topic thoroughly. Return structured findings.",
    tools=[google_search, web_scraper],
)

code_agent = Agent(
    name="coder",
    model="gemini-2.5-pro",
    instruction="Write clean, tested code based on specifications.",
    tools=[code_execution],
)

# Parent agent - coordinator
coordinator = Agent(
    name="coordinator",
    model="gemini-2.5-pro",
    instruction="""You coordinate a development team.
    Delegate research tasks to @researcher.
    Delegate coding tasks to @coder.
    Synthesize results into a final deliverable.""",
    sub_agents=[research_agent, code_agent],
)

# Run
session_service = InMemorySessionService()
runner = Runner(agent=coordinator, app_name="dev-team", session_service=session_service)
result = runner.run(user_id="dev", session_id="s1", new_message="Build a CLI tool for transcoding video files")
```

ADK's advantage is deep integration with Google Cloud. Deploy to Vertex AI Agent Engine, Cloud Run, or GKE with managed infrastructure, built-in auth, and Cloud Trace observability out of the box.

### Claude Code: Native Task Delegation

Claude Code handles multi-agent coordination through its built-in Task tool and custom [sub-agents](/blog/claude-code-sub-agents) defined in markdown files. No external framework needed.

```markdown

---
name: researcher
description: Researches technical topics using web search and documentation
tools:
  - WebSearch
  - WebFetch
  - Read
---

You are a technical research specialist. When given a topic:
1. Search for the latest documentation and release notes
2. Find working code examples
3. Identify common pitfalls and known issues
4. Return structured findings with source URLs
```

```markdown

---
name: implementer
description: Writes production code based on specifications
tools:
  - Read
  - Edit
  - Write
  - Bash
---

You are a senior developer. Write clean, typed, tested code.
Follow the project's existing patterns. Check CLAUDE.md for conventions.
```

In practice, Claude Code's orchestrator spawns Task agents that run in parallel:

```
User: "Add WebSocket support to the API with JWT auth"

Claude Code (orchestrator):
  -> Task 1 (researcher): "Find current best practices for WebSocket + JWT in Express"
  -> Task 2 (researcher): "Check our existing auth middleware implementation"
  -> Task 3 (implementer): "Scaffold the WebSocket server module" (after tasks 1-2)
  -> Task 4 (implementer): "Write integration tests" (after task 3)
```

The key advantage is that Claude Code agents share the project context inherently. They can read CLAUDE.md, access the file system, and understand the codebase without external tooling or API wiring.

## Choosing the Right Pattern

The decision tree is simpler than it looks.

**Start with fan-out/fan-in** if your subtasks are independent. Most tasks are more parallelizable than you think. Research, auditing, code generation for separate modules, testing different approaches - all fan-out candidates.

**Use a pipeline** when you have clear sequential dependencies. The output of stage N is a required input for stage N+1. Content creation (research -> write -> review -> publish) is the classic pipeline.

**Use hierarchical delegation** when the task requires adaptive planning. A supervisor that can reassign work, handle failures, and adjust priorities mid-execution. Complex project management, multi-file refactoring, or any workflow that might need replanning.

**Use blackboard** when agents need to iterate on shared state without direct communication. Code review cycles, collaborative editing, and convergence problems where the right answer emerges from multiple passes.

**Use handoffs** for routing problems. Customer support, debugging, or any workflow where the right specialist depends on runtime conditions.

**Use consensus** when correctness matters more than speed. Security-critical code, architectural decisions, or anywhere a single agent's bias might produce a suboptimal result.

## Production Considerations

### State Management

Every framework handles state differently, and this is where production systems diverge from demos.

**LangGraph** gives you explicit, typed state with reducers. Every state mutation is tracked. You can checkpoint, resume, and replay entire workflows. This is the strongest state management story in the ecosystem.

**CrewAI** uses shared memory (short-term, long-term, entity, and contextual). Agents can reference past interactions and build on prior knowledge. The trade-off is less explicit control over what gets remembered.

**AG2** uses MemoryStream, a pub/sub event bus that isolates state per conversation. Strong for concurrent users but requires more setup for cross-conversation persistence.

**Claude Code** uses the file system as state. Agents read and write files. Simple, debuggable, and zero infrastructure - but you need discipline about file organization.

### Error Handling

Agents fail. Models hallucinate. API calls time out. Production multi-agent systems need:

1. **Retry with context** - when an agent fails, retry with the error message in context so it can self-correct
2. **Fallback agents** - if the primary agent fails after retries, route to a different agent or model
3. **Circuit breakers** - if an agent loop exceeds N iterations without progress, break and escalate
4. **Structured outputs** - use JSON schemas or Pydantic models to validate agent outputs at every handoff point

```typescript
// Production error handling pattern
async function resilientAgentCall(
  agent: SubAgent,
  input: string,
  maxRetries: number = 3
): Promise {
  let lastError = "";

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const prompt = lastError
        ? `Previous attempt failed: ${lastError}\n\nOriginal task: ${input}`
        : input;

      const response = await client.messages.create({
        model: "claude-sonnet-4-5-20250514",
        max_tokens: 4096,
        system: agent.systemPrompt,
        messages: [{ role: "user", content: prompt }],
      });

      const output = response.content[0].type === "text" ? response.content[0].text : "";

      // Validate output structure
      if (agent.outputSchema) {
        agent.outputSchema.parse(JSON.parse(output));
      }

      return output;
    } catch (error) {
      lastError = error instanceof Error ? error.message : String(error);
    }
  }

  throw new Error(`Agent ${agent.name} failed after ${maxRetries} attempts: ${lastError}`);
}
```

### Cost Control

Multi-agent systems multiply your API costs. Three agents running in parallel cost 3x a single agent. A review loop that runs five iterations costs 5x a single pass.

Practical strategies:

- **Use cheaper models for simple tasks.** Route research and summarization to Claude Haiku or GPT-4o-mini. Reserve Sonnet or Opus for complex reasoning.
- **Set iteration caps.** Never let a review loop run indefinitely. Three iterations is usually enough.
- **Cache aggressively.** If multiple agents need the same context (file contents, API docs), fetch once and share.
- **Monitor token usage per agent.** The agent consuming the most tokens is either doing the most work or the most wasted work. Instrument and measure.

### Observability

You cannot debug a multi-agent system by reading logs. You need traces that show which agent ran when, what input it received, what output it produced, and how long it took.

LangGraph has built-in tracing through LangSmith. CrewAI supports verbose mode with per-agent logging. AG2 has step-through execution. For custom systems, OpenTelemetry spans per agent call give you the visibility you need.

## The Pragmatic Path

If you are starting from zero, here is the shortest path to production:

1. **Start with fan-out/fan-in using raw API calls.** No framework. Just `Promise.all()` with a merge step. This handles 60% of multi-agent use cases.

2. **Add a framework when you need loops or state.** If your agents need to iterate (review cycles, planning loops), LangGraph's state machine model makes those loops explicit and debuggable. If you want role-based teams with memory, CrewAI gets you there faster.

3. **Use Claude Code's native agents for development workflows.** If your multi-agent use case is "help me build software faster," Claude Code's sub-agent system is the most practical option because it already understands codebases, file systems, and development tools.

4. **Use OpenAI Agents SDK for customer-facing handoff flows.** The handoff primitive is first-class and the SDK is lightweight. Good for support bots, triage systems, and any application where requests need intelligent routing.

5. **Use Google ADK if you are in the Google Cloud ecosystem.** The deployment story to Vertex AI is seamless, and the hierarchical agent model maps well to organizational structures.

The framework choice matters less than the coordination pattern. Get the pattern right first, then pick the framework that makes that pattern easiest to implement and debug. Every framework listed here can implement every pattern. The question is which one makes your specific pattern feel natural rather than forced.

Build the simplest thing that works. Add complexity only when the simple thing fails. That advice applies to single-agent systems and multi-agent orchestration alike.

## Frequently Asked Questions

### What is multi-agent AI orchestration?

Multi-agent orchestration is the practice of coordinating multiple AI agents to work together on complex tasks. Instead of one agent doing everything, you decompose work across specialists - a researcher agent, a coding agent, a reviewer agent - and coordinate their outputs. The challenge is not building individual agents but making them communicate, share context, and resolve conflicts.

### Which multi-agent framework should I use in 2026?

It depends on your use case. For explicit control flow and debuggable state machines, use LangGraph. For role-based teams with shared memory, use CrewAI. For conversation-based coordination, use AutoGen/AG2. For customer-facing handoff flows, use OpenAI Agents SDK. For Google Cloud deployments, use Google ADK. For development workflows, use Claude Code's native sub-agents. Most teams start with raw API calls and `Promise.all()` before adopting a framework.

### What is the difference between fan-out and pipeline patterns?

Fan-out (scatter-gather) runs multiple agents in parallel on independent subtasks and merges their outputs. Pipeline runs agents sequentially where each stage transforms the previous output. Use fan-out when subtasks have no dependencies on each other (research, auditing, generating alternatives). Use pipeline when there are clear sequential dependencies (research then write then review).

### How do AI agents communicate with each other?

Agents communicate through four main mechanisms: shared state (blackboard pattern), message passing (conversation-based frameworks like AutoGen), explicit handoffs (OpenAI Agents SDK, Claude Code sub-agents), or typed state transitions (LangGraph). The right choice depends on whether you need reactive updates, turn-taking, or explicit control flow.

### What is the blackboard pattern in multi-agent systems?

The blackboard pattern uses shared state as the communication channel. Agents read from and write to a common state object without directly messaging each other. A controller monitors the state and triggers agents when relevant sections change. This pattern works well for iterative refinement tasks like code review cycles where agents need to react to each other's work.

### How do I handle errors in multi-agent systems?

Production multi-agent systems need four error handling strategies: retry with context (include the error message so the agent can self-correct), fallback agents (route to a different agent or model after retries fail), circuit breakers (break infinite loops after N iterations without progress), and structured output validation (use JSON schemas to validate agent outputs at every handoff point).

### How expensive are multi-agent systems to run?

Multi-agent systems multiply your API costs. Three agents running in parallel cost 3x a single agent. A review loop with five iterations costs 5x a single pass. Control costs by using cheaper models for simple tasks (Haiku for research, Sonnet for complex reasoning), setting iteration caps on loops, caching shared context across agents, and monitoring token usage per agent.

### Can I use different AI models in the same multi-agent system?

Yes. Most frameworks support mixing models. Route simple tasks (summarization, research) to faster, cheaper models like Claude Haiku or GPT-4o-mini. Reserve powerful models like Claude Sonnet or GPT-4 for complex reasoning, code generation, and final synthesis. LangGraph, CrewAI, and custom implementations all support per-agent model configuration.


The MCP Server Ecosystem: A Developer's Guide for 2026
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT

## The State of the Ecosystem

MCP was released by [Anthropic](/blog/anthropic-vs-openai-developer-experience) in November 2024. Eighteen months later, PulseMCP indexes over 12,000 servers. OpenAI and Google adopted the protocol. It was donated to the Linux Foundation's Agentic AI Foundation. Pinterest deployed it in production for engineering workflows. Raycast supports it natively. The protocol won.

For the broader MCP map, pair this with [What Is MCP (Model Context Protocol)? A TypeScript Developer's Guide](/blog/what-is-mcp) and [The Complete Guide to MCP Servers](/blog/complete-guide-mcp-servers); those pieces cover the concepts and server-selection layer behind this article.

But 12,000 servers does not mean 12,000 useful servers. The vast majority are weekend projects, proof-of-concept demos, or abandoned repos with broken dependencies. The signal-to-noise ratio is terrible. Installing a random MCP server from a GitHub search is a coin flip between a productivity boost and a debugging session.

This guide cuts through the noise. It covers the servers that actually work in production workflows - tested, maintained, and useful for real development. Organized by category, with honest assessments, working configurations, and the opinionated rankings you will not find in a neutral directory listing. If you would rather answer a few questions and get a curated shortlist for your specific stack, the [MCP picker](/which-tool) is the fastest path.

## How to Read This Guide

Every server entry includes:

- **What it does** in plain language
- **Install command** you can copy-paste
- **Configuration** for [Claude Code](/blog/what-is-claude-code-complete-guide-2026) (works in Cursor and other MCP clients with minor format changes)
- **Verdict** - whether it is worth installing and for whom

All configurations use the Claude Code `settings.json` format. For Claude Code, add these to `~/.claude/settings.json` or your project's `.claude/settings.json` under the `mcpServers` key:

```json
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"],
      "env": {}
    }
  }
}
```

## Tier 1: Install These First

These servers solve the most common pain points. If you use an [AI coding tool](/blog/ai-coding-tools-comparison-matrix-2026) daily, these should be in your config file already.

### Context7 - Documentation Lookup

The most popular MCP server in the ecosystem by a wide margin, and for good reason. Context7 fetches current documentation for any library, framework, or SDK directly into your agent's context. No more hallucinated API signatures. No more answers based on two-year-old training data.

```json
{
  "context7": {
    "command": "npx",
    "args": ["-y", "@context7/mcp-server"]
  }
}
```

**What it actually does:** When your agent needs to look up how `useActionState` works in React 19, or what the current Prisma migration syntax is, it queries Context7's index of library documentation and returns the relevant sections. The documentation is pulled from official sources and kept current.

**Verdict:** Essential. Install this before anything else. The single biggest quality improvement for AI-generated code is giving the agent access to current documentation instead of relying on training data that may be months or years stale.

### Playwright - Browser Automation

The official Playwright MCP server gives your agent a real browser. It can navigate pages, fill forms, click buttons, take screenshots, and read page content - all through accessibility snapshots rather than pixel-level vision, which makes it fast and deterministic.

```json
{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-playwright"]
  }
}
```

**What it actually does:** Your agent can open a URL, interact with the page like a user, and extract information. This is transformative for testing web applications, scraping data from sites that require JavaScript rendering, and verifying that your UI changes look correct.

**Common use cases:**
- Smoke-testing your app after changes ("open localhost:3000 and verify the login flow works")
- Extracting data from web apps that do not have APIs
- Screenshot-based visual verification of UI components
- Filling out forms and testing multi-step workflows

**Verdict:** Essential for web developers. If you build anything that runs in a browser, install this.

### GitHub - Repository Operations

The official GitHub MCP server covers the full GitHub API surface: issues, pull requests, repositories, code search, and file operations. Your agent can create issues, review PRs, search code across repositories, and manage branches without leaving the conversation.

```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-github"],
    "env": {
      "GITHUB_TOKEN": "ghp_your_token_here"
    }
  }
}
```

**What it actually does:** Instead of context-switching to the GitHub web UI, you can tell your agent "create an issue for the auth bug we just discussed" or "check if there are any open PRs that touch the billing module" and it handles the API calls directly.

**Verdict:** Essential for any team using GitHub. The time savings from not context-switching to the web UI compound quickly.

### Filesystem - Cross-Project File Access

The official Anthropic filesystem server lets your agent read and write files outside the current project directory. Claude Code already has file access within your project, but this server extends that reach to other directories you specify.

```json
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@anthropic-ai/mcp-server-filesystem",
      "/Users/you/notes",
      "/Users/you/other-project"
    ]
  }
}
```

**What it actually does:** Your agent can reference documentation in your notes directory, copy patterns from another project, or read configuration files that live outside the repo.

**Verdict:** Essential if you work across multiple projects or keep reference material outside your repos. The security model is solid - it only accesses the directories you explicitly list.

## Tier 2: Install Based on Your Stack

These servers are excellent but serve specific use cases. Install the ones that match your development workflow.

### Web Scraping MCP Servers

Several MCP servers offer web scraping capabilities, returning clean markdown from any URL. The best ones handle JavaScript-rendered pages, rate limiting, and content extraction automatically. Unlike Playwright (which gives you a full browser to control), scraping-focused servers are optimized for bulk content extraction.

**What they do:** Your agent can scrape any URL and get back clean markdown instead of raw HTML. Most also include a search function that finds relevant pages for a query. This is the tool your agent reaches for when it needs to research a topic, read a blog post, or extract structured data from a web page.

**Verdict:** Highly recommended for any workflow that involves web research. Most require an API key but free tiers are generous enough for personal use. If your agent does research tasks regularly, a scraping MCP server pays for itself immediately.

### PostgreSQL / Neon - Database Operations

Multiple MCP servers exist for PostgreSQL. The best option depends on whether you use a hosted provider or self-managed Postgres.

**For Neon (serverless Postgres):**
```json
{
  "neon": {
    "command": "npx",
    "args": ["-y", "@neondatabase/mcp-server-neon"],
    "env": {
      "NEON_API_KEY": "your_neon_api_key"
    }
  }
}
```

**For generic PostgreSQL:**
```json
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
    "env": {
      "POSTGRES_CONNECTION_STRING": "postgresql://user:pass@host:5432/db"
    }
  }
}
```

**What it actually does:** Your agent can query your database directly. Ask "what are the most common user roles in the database?" and it runs the SQL and returns the results. It can also inspect schemas, explain query plans, and help you write migrations based on the actual state of your database rather than outdated documentation.

**Verdict:** Install if you work with PostgreSQL regularly. Having your agent see the real schema and data (in development environments) produces dramatically better database code. Do not point this at production databases without read-only credentials.

### Sentry - Error Monitoring

The Sentry MCP server connects your agent to your error monitoring data. It can look up recent errors, read stack traces, find related issues, and help you understand what is breaking and why.

```json
{
  "sentry": {
    "command": "npx",
    "args": ["-y", "@sentry/mcp-server"],
    "env": {
      "SENTRY_AUTH_TOKEN": "your_sentry_token",
      "SENTRY_ORG": "your-org"
    }
  }
}
```

**What it actually does:** Instead of opening the Sentry dashboard, searching for an error, reading the stack trace, and then pasting it into your agent, you say "look at the most recent unhandled exceptions in the API" and the agent pulls the data directly. It reads the stack trace, correlates it with your codebase, and suggests a fix.

**Verdict:** Install if you use Sentry. The debugging workflow becomes: "check Sentry for recent errors in the auth module and fix them" as a single prompt. Without this server, the same task requires manual data gathering and copy-pasting.

### Supabase - Backend as a Service

If your stack includes Supabase, the official MCP server gives your agent access to your project's database, auth, storage, and edge functions.

```json
{
  "supabase": {
    "command": "npx",
    "args": ["-y", "@supabase/mcp-server"],
    "env": {
      "SUPABASE_URL": "https://your-project.supabase.co",
      "SUPABASE_SERVICE_KEY": "your_service_role_key"
    }
  }
}
```

**Verdict:** Essential if you use Supabase. Skip if you do not.

### Upstash - Redis and Kafka

Upstash provides serverless Redis and Kafka. Their MCP server lets your agent interact with your caches, queues, and real-time data pipelines.

```json
{
  "upstash": {
    "command": "npx",
    "args": ["-y", "@upstash/mcp-server"],
    "env": {
      "UPSTASH_REDIS_REST_URL": "https://your-redis.upstash.io",
      "UPSTASH_REDIS_REST_TOKEN": "your_token"
    }
  }
}
```

**Verdict:** Install if you use Upstash. Particularly useful for debugging caching issues - your agent can inspect cache contents, check TTLs, and verify that your caching logic works correctly.

## Tier 3: Specialized Workflow Servers

These servers are not for everyone, but they are the best in their category for specific workflows.

### Zapier - Cross-App Automation

Zapier's MCP server connects your agent to almost 8,000 apps. Google Sheets, Slack, Jira, HubSpot, Notion, Airtable - if it has an API, Zapier probably has a connection.

```json
{
  "zapier": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-zapier"],
    "env": {
      "ZAPIER_MCP_API_KEY": "your_zapier_key"
    }
  }
}
```

**What it actually does:** Your agent can trigger Zapier actions and read data from connected apps. "Post a summary of today's changes to the #engineering Slack channel." "Create a Jira ticket for the bug we found." "Add a row to the project tracking sheet."

**Verdict:** Powerful if your team uses Zapier already. The breadth of integrations is unmatched. The trade-off is latency - every action routes through Zapier's infrastructure, so it is slower than direct API integrations. Best for low-frequency, high-value automations rather than tight development loops.

### Linear - Project Management

Linear's MCP server gives your agent access to issues, projects, cycles, and team data. It can create issues, update status, assign work, and query your backlog.

```json
{
  "linear": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-linear"],
    "env": {
      "LINEAR_API_KEY": "lin_api_your_key"
    }
  }
}
```

**Verdict:** Install if your team uses Linear. The "fix the bug and update the ticket" workflow becomes a single prompt. Without it, you fix the bug in Claude Code, then open Linear separately to update the ticket.

### Cloudflare - Workers and Infrastructure

Cloudflare's MCP server covers Workers, KV, R2, D1, and DNS. Your agent can deploy Workers, manage KV namespaces, query D1 databases, and update DNS records.

```json
{
  "cloudflare": {
    "command": "npx",
    "args": ["-y", "@cloudflare/mcp-server"],
    "env": {
      "CLOUDFLARE_API_TOKEN": "your_cf_token",
      "CLOUDFLARE_ACCOUNT_ID": "your_account_id"
    }
  }
}
```

**Verdict:** Essential for Cloudflare-heavy stacks. If you deploy Workers regularly, this removes a significant amount of context-switching between your editor and the Cloudflare dashboard.

### Notion - Knowledge Base

Notion's MCP server lets your agent read and write pages, databases, and blocks. It can search your workspace, create new pages, and update existing content.

```json
{
  "notion": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-notion"],
    "env": {
      "NOTION_API_KEY": "ntn_your_key"
    }
  }
}
```

**Verdict:** Useful if your team's documentation lives in Notion. Your agent can look up internal docs, update runbooks, and create post-mortems without you copy-pasting between apps.

### Slack - Team Communication

The Slack MCP server lets your agent read channels, post messages, search message history, and interact with threads.

```json
{
  "slack": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-slack"],
    "env": {
      "SLACK_BOT_TOKEN": "xoxb-your-bot-token"
    }
  }
}
```

**Verdict:** Useful for team-integrated workflows. "Search Slack for any discussion about the payments migration" is faster than manually searching. The posting capability is handy for automated status updates. Be thoughtful about which channels the bot token has access to.

## Tier 4: Niche but Worth Knowing

### Memory - Persistent Agent Knowledge

The Memory MCP server gives your agent a key-value store that persists across sessions. It can save facts, preferences, and context that carry over between conversations.

```json
{
  "memory": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-memory"],
    "env": {
      "MEMORY_FILE": "/Users/you/.claude/memory.json"
    }
  }
}
```

**Verdict:** Interesting for long-running projects where you want the agent to remember decisions and preferences across sessions. Less necessary if you already use CLAUDE.md and skills files for persistent context (which is the approach I prefer - explicit over implicit).

### Puppeteer - Headless Browser

An alternative to Playwright for [browser automation](/blog/claude-code-chrome-automation), using Puppeteer under the hood. Some teams prefer it if they already have Puppeteer infrastructure.

```json
{
  "puppeteer": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-puppeteer"]
  }
}
```

**Verdict:** Use Playwright instead unless you have a specific reason to prefer Puppeteer. The Playwright MCP server is more actively maintained and has better accessibility snapshot support.

### Docker - Container Management

Manage Docker containers, images, and compose stacks from your agent.

```json
{
  "docker": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-docker"]
  }
}
```

**Verdict:** Useful for container-heavy workflows. Your agent can inspect running containers, read logs, and restart services. Less necessary if you use Claude Code's Bash tool to run Docker commands directly (which works fine for most cases).

### SQLite - Local Database

A lightweight server for working with SQLite databases. Good for prototyping and working with local data stores.

```json
{
  "sqlite": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-sqlite", "--db-path", "/path/to/database.db"]
  }
}
```

**Verdict:** Install if you work with SQLite. The ability for your agent to inspect and query the actual database while writing code that interacts with it eliminates an entire class of bugs.

## Configuration Strategy

### Start Minimal

Do not install 15 MCP servers on day one. Each server is a process that starts with Claude Code, consumes memory, and adds latency to tool discovery. Start with Tier 1, add Tier 2 servers that match your stack, and only reach for Tier 3 and 4 when you have a specific need.

### Project-Level vs Global Configuration

Put servers you use across all projects in `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "context7": { "command": "npx", "args": ["-y", "@context7/mcp-server"] },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-github"],
      "env": { "GITHUB_TOKEN": "ghp_xxx" }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/Users/you/notes"]
    }
  }
}
```

Put project-specific servers in `.claude/settings.json` at the project root:

```json
{
  "mcpServers": {
    "neon": {
      "command": "npx",
      "args": ["-y", "@neondatabase/mcp-server-neon"],
      "env": { "NEON_API_KEY": "your_key" }
    },
    "sentry": {
      "command": "npx",
      "args": ["-y", "@sentry/mcp-server"],
      "env": { "SENTRY_AUTH_TOKEN": "your_token", "SENTRY_ORG": "your-org" }
    }
  }
}
```

This keeps your global config clean and prevents API keys for one project from leaking into another.

### Security Considerations

MCP servers run as processes on your machine with access to whatever credentials you provide. A few rules:

1. **Use scoped tokens.** Never give a server your GitHub personal access token with full repo access if it only needs read access to public repos. Create fine-grained tokens with the minimum required permissions.

2. **Separate dev and prod credentials.** The database MCP server should never connect to your production database. Use development or staging credentials only.

3. **Audit server source code.** Before installing a community MCP server, check the GitHub repo. Read the code. A malicious server with access to your filesystem token could exfiltrate code. Stick to official servers from Anthropic and major vendors, or audit community servers before installing.

4. **Use environment variables, not hardcoded keys.** Store API keys in your shell profile or a `.env` file and reference them in your MCP config. Never commit API keys to version control.

## The Ecosystem's Trajectory

The MCP ecosystem is following the same curve as npm packages circa 2014. Explosive growth in quantity. Wildly inconsistent quality. A small number of essential packages rising to dominance while thousands of alternatives languish.

The consolidation is already happening. Official servers from platform vendors (Anthropic, GitHub, Cloudflare, Sentry, Supabase, Linear) are winning because they are maintained by the teams that own the APIs. Community servers that do not achieve critical mass are going unmaintained within months.

The practical implication: favor official vendor servers over community alternatives. When both exist for the same service, the official one will be better maintained, more secure, and more complete. The community alternative might have a feature the official server lacks today, but that gap closes quickly.

The next wave is server composition - running multiple servers together in coordinated workflows. Your agent queries the database, finds an error pattern, searches Sentry for related exceptions, creates a GitHub issue, and posts a summary to Slack. Each step uses a different MCP server, but the workflow feels like a single coherent action. The protocol already supports this. The tooling to make it seamless is catching up.

Choose servers that solve problems you have today. Install them, configure them, and build workflows around them. That is how you get value from MCP - not by installing everything, but by integrating the right servers deeply into your daily development practice.

## Frequently Asked Questions

### What is MCP and why should developers care?

MCP (Model Context Protocol) is a standard protocol that lets AI coding tools connect to external services - databases, APIs, browsers, project management tools, and more. It was created by Anthropic, adopted by OpenAI and Google, and donated to the Linux Foundation. Developers should care because MCP servers dramatically expand what your AI assistant can do: query your database, browse the web, create GitHub issues, or post to Slack - all from within your coding session.

### How many MCP servers should I install?

Start with 3-5 essential servers (Context7, Playwright, GitHub, Filesystem) and add more only when you have specific needs. Each server is a process that consumes memory and adds latency to tool discovery. Installing 15 servers "just in case" slows down your workflow without adding value. Favor depth over breadth - learn to use a few servers well before expanding.

### Where do I put MCP server configuration?

Global servers you use across all projects go in `~/.claude/settings.json`. Project-specific servers go in `.claude/settings.json` at your project root. This keeps your global config clean and prevents API keys from leaking between projects. Environment variables for sensitive credentials can reference your shell profile or a `.env` file.

### Are community MCP servers safe to use?

Use caution with community servers. MCP servers run as processes on your machine with access to whatever credentials you provide. Stick to official servers from Anthropic and major vendors (GitHub, Cloudflare, Supabase, Sentry, Linear) when possible. If you use community servers, audit the source code first, use scoped API tokens with minimal permissions, and never connect to production databases.

### What is the difference between Playwright and Puppeteer MCP servers?

Both provide browser automation, but the Playwright MCP server (from Anthropic) is recommended. It uses accessibility snapshots rather than pixel-level vision, making it faster and more deterministic. The Playwright server is also more actively maintained. Use Puppeteer only if you have existing Puppeteer infrastructure you need to integrate with.

### Can MCP servers work with Cursor, not just Claude Code?

Yes. MCP is a standard protocol supported by multiple AI coding tools. The configuration format varies slightly between tools, but the same MCP servers work with Claude Code, Cursor, Cline, and other MCP-compatible clients. Check your tool's documentation for the exact configuration syntax.

### How do I debug MCP server issues?

Check if the server process is running with `ps aux | grep mcp`. Verify your configuration syntax in `settings.json`. Test API credentials independently before adding them to MCP config. Use scoped, minimal-permission tokens to isolate authentication issues. Most failures are either configuration typos or credential problems rather than server bugs.

### What MCP servers should a TypeScript developer install first?

Start with Context7 (current documentation lookup), Playwright (browser testing), GitHub (repo operations), and Filesystem (cross-project file access). Add PostgreSQL/Neon if you use those databases, and Sentry if you use it for error monitoring. These cover the most common workflows for TypeScript web development without overloading your setup.


Self-Improving AI Agents: Building Systems That Learn From Their Mistakes
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT
Most AI agents are goldfish. They execute a task, succeed or fail, and forget everything. The next time they encounter the same problem, they make the same mistakes. Every session starts from zero.

Self-improving agents break this cycle. They reflect on what happened, extract lessons from successes and failures, store those lessons in accessible formats, and retrieve them when relevant. Over time, they get measurably better at their tasks.

This is not speculative AI research. These patterns are running in production today. Here is how to build agents that actually learn.

## The Reflection Pattern

Reflection is the mechanism that converts experience into knowledge. After an agent completes a task (or fails at one), a reflection step analyzes what happened and extracts transferable lessons.

For the design side of the same problem, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) with [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

### Basic Reflection Loop

The simplest reflection pattern has three steps: execute, evaluate, extract.

```typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

interface Reflection {
  task: string;
  outcome: "success" | "failure" | "partial";
  lessons: string[];
  confidence: number;
  timestamp: string;
}

async function executeWithReflection(
  task: string,
  context: string
): Promise<{ result: string; reflection: Reflection }> {
  // Step 1: Execute the task
  const executionResult = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 4096,
    system: context,
    messages: [{ role: "user", content: task }],
  });

  const result =
    executionResult.content[0].type === "text"
      ? executionResult.content[0].text
      : "";

  // Step 2: Evaluate the outcome
  const evaluationResult = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 1024,
    messages: [
      {
        role: "user",
        content: `Evaluate this task execution:

Task: ${task}
Result: ${result}

Rate the outcome as "success", "failure", or "partial".
Extract 1-3 specific, actionable lessons learned.
Rate your confidence in each lesson from 0.0 to 1.0.

Respond as JSON:
{
  "outcome": "success|failure|partial",
  "lessons": ["lesson 1", "lesson 2"],
  "confidence": 0.85
}`,
      },
    ],
  });

  const evaluation = JSON.parse(
    evaluationResult.content[0].type === "text"
      ? evaluationResult.content[0].text
      : "{}"
  );

  const reflection: Reflection = {
    task,
    outcome: evaluation.outcome,
    lessons: evaluation.lessons,
    confidence: evaluation.confidence,
    timestamp: new Date().toISOString(),
  };

  return { result, reflection };
}
```

This is the foundation. The agent does work, then a separate evaluation pass examines the work and extracts lessons. The evaluation pass uses the same model but with a different prompt focused on analysis rather than execution.

### Why Separate Execution from Evaluation

A common mistake is asking the agent to execute and reflect simultaneously. "Do this task and also think about what you learned." This produces worse execution and worse reflection because the model splits its attention.

Separation works better for two reasons:

**Cognitive clarity.** The execution pass focuses entirely on the task. The evaluation pass focuses entirely on analysis. Neither is compromised by the other.

**Different system prompts.** The execution pass might have a system prompt optimized for coding ("You are an expert TypeScript developer"). The evaluation pass has a system prompt optimized for analysis ("You are a quality analyst reviewing agent performance"). Specialization improves both outputs.

## Memory Architectures

Reflection produces lessons. Memory stores them for retrieval. The architecture of your memory system determines whether lessons are available when they matter.

### Architecture 1: Flat File Memory

The simplest approach. Store all reflections in a single JSON file, read at session start.

```typescript
import { readFile, writeFile } from "fs/promises";

const MEMORY_PATH = ".agent/memory.json";

interface MemoryStore {
  reflections: Reflection[];
  skills: Skill[];
  corrections: Correction[];
}

async function loadMemory(): Promise {
  try {
    const data = await readFile(MEMORY_PATH, "utf-8");
    return JSON.parse(data);
  } catch {
    return { reflections: [], skills: [], corrections: [] };
  }
}

async function saveReflection(reflection: Reflection): Promise {
  const memory = await loadMemory();
  memory.reflections.push(reflection);

  // Prune low-confidence reflections when memory gets large
  if (memory.reflections.length > 200) {
    memory.reflections = memory.reflections
      .sort((a, b) => b.confidence - a.confidence)
      .slice(0, 150);
  }

  await writeFile(MEMORY_PATH, JSON.stringify(memory, null, 2));
}

async function getRelevantMemories(task: string): Promise {
  const memory = await loadMemory();

  // Simple keyword matching for retrieval
  const words = task.toLowerCase().split(/\s+/);
  const relevant = memory.reflections.filter((r) =>
    words.some(
      (w) =>
        r.task.toLowerCase().includes(w) ||
        r.lessons.some((l) => l.toLowerCase().includes(w))
    )
  );

  return relevant
    .slice(0, 10)
    .map(
      (r) =>
        `[${r.outcome}] ${r.task}: ${r.lessons.join("; ")} (confidence: ${r.confidence})`
    )
    .join("\n");
}
```

Flat file memory works for agents with fewer than a few hundred reflections. Beyond that, keyword matching becomes unreliable and loading the entire file wastes tokens.

**When to use:** Personal agents, project-specific agents, any system where the total reflection count stays under 500.

### Architecture 2: Structured Memory with Categories

Split memory into categories so the agent loads only relevant context.

```typescript
interface StructuredMemory {
  technical: {
    bugs: Reflection[];
    patterns: Reflection[];
    performance: Reflection[];
  };
  process: {
    planning: Reflection[];
    testing: Reflection[];
    deployment: Reflection[];
  };
  domain: {
    [key: string]: Reflection[];
  };
}

async function categorizeAndStore(reflection: Reflection): Promise {
  const memory = await loadStructuredMemory();

  // Use the model to categorize the reflection
  const categoryResult = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 256,
    messages: [
      {
        role: "user",
        content: `Categorize this lesson into one category.

Lesson: ${reflection.lessons.join("; ")}
Task: ${reflection.task}

Categories:
- technical/bugs: Bug fixes and error handling
- technical/patterns: Code patterns and architecture
- technical/performance: Performance optimization
- process/planning: Task planning and decomposition
- process/testing: Testing strategies
- process/deployment: Deployment and operations
- domain/{topic}: Domain-specific knowledge

Respond with just the category path, e.g., "technical/bugs"`,
      },
    ],
  });

  const category =
    categoryResult.content[0].type === "text"
      ? categoryResult.content[0].text.trim()
      : "domain/general";

  // Store in the appropriate category
  const [top, sub] = category.split("/");
  if (!memory[top]) memory[top] = {};
  if (!memory[top][sub]) memory[top][sub] = [];
  memory[top][sub].push(reflection);

  await saveStructuredMemory(memory);
}

async function retrieveByCategory(
  categories: string[]
): Promise {
  const memory = await loadStructuredMemory();
  const results: Reflection[] = [];

  for (const category of categories) {
    const [top, sub] = category.split("/");
    if (memory[top]?.[sub]) {
      results.push(...memory[top][sub]);
    }
  }

  return results.sort((a, b) => b.confidence - a.confidence).slice(0, 20);
}
```

Structured memory solves the relevance problem. When the agent is debugging, it loads `technical/bugs`. When it is deploying, it loads `process/deployment`. Irrelevant memories stay out of the context window.

**When to use:** Agents that handle diverse tasks across multiple domains. The categorization overhead is worth it when the total memory exceeds a few hundred entries.

### Architecture 3: Embedding-Based Retrieval

For large memory stores, use vector embeddings to find semantically relevant memories.

```typescript
interface EmbeddedReflection extends Reflection {
  embedding: number[];
}

async function embedReflection(
  reflection: Reflection
): Promise {
  const text = `${reflection.task} ${reflection.lessons.join(" ")}`;

  // Using a local embedding model or API
  const embedding = await getEmbedding(text);

  return { ...reflection, embedding };
}

async function findSimilar(
  query: string,
  topK: number = 5
): Promise {
  const queryEmbedding = await getEmbedding(query);
  const allMemories = await loadEmbeddedMemories();

  // Cosine similarity search
  const scored = allMemories.map((m) => ({
    reflection: m,
    score: cosineSimilarity(queryEmbedding, m.embedding),
  }));

  return scored
    .sort((a, b) => b.score - a.score)
    .slice(0, topK)
    .map((s) => s.reflection);
}

function cosineSimilarity(a: number[], b: number[]): number {
  let dotProduct = 0;
  let normA = 0;
  let normB = 0;
  for (let i = 0; i < a.length; i++) {
    dotProduct += a[i] * b[i];
    normA += a[i] * a[i];
    normB += b[i] * b[i];
  }
  return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
}
```

Embedding-based retrieval finds semantically similar memories even when the exact keywords differ. A lesson about "database connection pooling" retrieves when the agent encounters "Postgres timeout errors" because the embeddings are close in semantic space.

**When to use:** Agents with thousands of reflections, or agents that handle tasks where keyword matching is insufficient.

## Skill Accumulation

Reflections are raw experience. Skills are refined knowledge. The skill extraction process converts multiple related reflections into a reusable, structured skill.

### From Reflections to Skills

```typescript
interface Skill {
  name: string;
  description: string;
  steps: string[];
  constraints: string[];
  confidence: number;
  sourceReflections: number;
  lastUpdated: string;
}

async function extractSkill(
  reflections: Reflection[],
  domain: string
): Promise {
  const reflectionText = reflections
    .map(
      (r) =>
        `Task: ${r.task}\nOutcome: ${r.outcome}\nLessons: ${r.lessons.join("; ")}`
    )
    .join("\n\n");

  const result = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: `Analyze these ${reflections.length} related experiences in the "${domain}" domain and extract a reusable skill.

${reflectionText}

Create a skill with:
1. A clear name (verb + noun, e.g., "Debug Database Connections")
2. A one-sentence description
3. Ordered steps that work reliably
4. Constraints (things to avoid, based on failures)
5. Confidence level (0.0-1.0) based on how many successes vs failures

Respond as JSON:
{
  "name": "...",
  "description": "...",
  "steps": ["step 1", "step 2"],
  "constraints": ["never do X", "always check Y"],
  "confidence": 0.85
}`,
      },
    ],
  });

  const skillData = JSON.parse(
    result.content[0].type === "text" ? result.content[0].text : "{}"
  );

  return {
    ...skillData,
    sourceReflections: reflections.length,
    lastUpdated: new Date().toISOString(),
  };
}
```

The skill extraction prompt does the heavy lifting: it reads multiple experiences and synthesizes them into a repeatable procedure. The constraints are particularly valuable because they encode failure modes. An agent with a skill that says "never use raw SQL for schema changes" will not make that mistake even if its base training would suggest it.

### Skill Evolution

Skills are not static. As the agent accumulates more experience, skills should be updated with new steps, refined constraints, and adjusted confidence levels.

```typescript
async function evolveSkill(
  existing: Skill,
  newReflections: Reflection[]
): Promise {
  const reflectionText = newReflections
    .map(
      (r) =>
        `Task: ${r.task}\nOutcome: ${r.outcome}\nLessons: ${r.lessons.join("; ")}`
    )
    .join("\n\n");

  const result = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: `Update this existing skill based on new experiences.

Current skill:
Name: ${existing.name}
Steps: ${existing.steps.join("\n")}
Constraints: ${existing.constraints.join("\n")}
Confidence: ${existing.confidence}
Based on: ${existing.sourceReflections} experiences

New experiences:
${reflectionText}

Update the skill:
- Add new steps if the new experiences reveal missing procedures
- Add new constraints if failures reveal new pitfalls
- Remove steps that new experience shows are unnecessary
- Adjust confidence based on success/failure ratio
- Keep what works, fix what doesn't

Respond as the updated skill JSON.`,
      },
    ],
  });

  const updated = JSON.parse(
    result.content[0].type === "text" ? result.content[0].text : "{}"
  );

  return {
    ...updated,
    sourceReflections: existing.sourceReflections + newReflections.length,
    lastUpdated: new Date().toISOString(),
  };
}
```

Skill evolution is where the compounding effect becomes visible. A skill based on 5 reflections is rough and general. The same skill after 50 reflections is specific, battle-tested, and reliable. Each new experience either reinforces existing steps (increasing confidence) or reveals gaps (adding new steps or constraints).

### The Skill Library

Over time, an agent accumulates a library of skills that covers its common tasks. The library structure matters for retrieval.

```typescript
interface SkillLibrary {
  skills: Map;
  index: Map; // keyword -> skill names
}

async function findApplicableSkills(
  task: string,
  library: SkillLibrary
): Promise {
  const words = task.toLowerCase().split(/\s+/);
  const candidateNames = new Set();

  for (const word of words) {
    const matches = library.index.get(word) || [];
    matches.forEach((name) => candidateNames.add(name));
  }

  const candidates = Array.from(candidateNames)
    .map((name) => library.skills.get(name))
    .filter((s): s is Skill => s !== undefined);

  // Sort by confidence, then by recency
  return candidates
    .sort(
      (a, b) =>
        b.confidence - a.confidence ||
        new Date(b.lastUpdated).getTime() - new Date(a.lastUpdated).getTime()
    )
    .slice(0, 3);
}
```

The agent consults its skill library before starting a task. If relevant skills exist, they provide a starting procedure and known constraints. If no skills exist, the agent operates from its base capabilities and generates new reflections that may seed future skills.

## Correction Tracking

Corrections are the highest-signal input for self-improvement. When a human corrects an agent, that correction represents a gap between the agent's behavior and the desired behavior.

```typescript
interface Correction {
  context: string;
  agentBehavior: string;
  humanCorrection: string;
  category: string;
  timestamp: string;
  applied: boolean;
}

async function processCorrection(
  context: string,
  agentBehavior: string,
  humanCorrection: string
): Promise {
  // Categorize the correction
  const categoryResult = await client.messages.create({
    model: "claude-sonnet-4-6-20260409",
    max_tokens: 256,
    messages: [
      {
        role: "user",
        content: `Categorize this correction:
Agent did: ${agentBehavior}
Human corrected to: ${humanCorrection}

Categories: style, logic, architecture, security, performance, convention, other
Respond with just the category.`,
      },
    ],
  });

  const category =
    categoryResult.content[0].type === "text"
      ? categoryResult.content[0].text.trim()
      : "other";

  const correction: Correction = {
    context,
    agentBehavior,
    humanCorrection,
    category,
    timestamp: new Date().toISOString(),
    applied: false,
  };

  await storeCorrection(correction);

  // Check if we have enough corrections in this category to update a skill
  const categoryCorrections = await getCorrectionsByCategory(category);
  if (categoryCorrections.length >= 3) {
    await updateSkillFromCorrections(category, categoryCorrections);
  }

  return correction;
}
```

The threshold of three corrections before updating a skill prevents overreaction to a single data point. One correction might be situational. Three corrections in the same category indicate a systematic gap.

### Correction Confidence Decay

Not all corrections age equally. A correction from yesterday is more relevant than one from three months ago because the codebase, the developer's preferences, and the project conventions may have changed.

```typescript
function correctionWeight(correction: Correction): number {
  const ageInDays =
    (Date.now() - new Date(correction.timestamp).getTime()) /
    (1000 * 60 * 60 * 24);

  // Half-life of 30 days
  return Math.exp(-0.693 * (ageInDays / 30));
}

async function getWeightedCorrections(
  category: string
): Promise {
  const corrections = await getCorrectionsByCategory(category);
  return corrections
    .map((c) => ({ ...c, weight: correctionWeight(c) }))
    .filter((c) => c.weight > 0.1) // Discard corrections older than ~100 days
    .sort((a, b) => b.weight - a.weight);
}
```

The 30-day half-life means recent corrections weigh heavily while old ones fade. This prevents the agent from following outdated preferences.

## Putting It All Together

Here is the complete self-improving agent loop, combining execution, reflection, memory, and skill accumulation.

```typescript
async function selfImprovingAgent(task: string): Promise {
  // 1. Load relevant context
  const memories = await getRelevantMemories(task);
  const skills = await findApplicableSkills(task, await loadSkillLibrary());
  const corrections = await getRecentCorrections(task);

  // 2. Build enhanced context
  const context = buildContext(memories, skills, corrections);

  // 3. Execute with enhanced context
  const { result, reflection } = await executeWithReflection(task, context);

  // 4. Store the reflection
  await saveReflection(reflection);

  // 5. Check if any skills need updating
  if (reflection.lessons.length > 0) {
    const relatedReflections = await findRelatedReflections(reflection);
    if (relatedReflections.length >= 5) {
      const existingSkill = await findMatchingSkill(task);
      if (existingSkill) {
        await evolveSkill(existingSkill, [reflection]);
      } else {
        const newSkill = await extractSkill(relatedReflections, task);
        await addToSkillLibrary(newSkill);
      }
    }
  }

  return result;
}

function buildContext(
  memories: string,
  skills: Skill[],
  corrections: Correction[]
): string {
  let context = "You are an AI agent that learns from experience.\n\n";

  if (skills.length > 0) {
    context += "## Relevant Skills\n\n";
    for (const skill of skills) {
      context += `### ${skill.name}\n`;
      context += `${skill.description}\n`;
      context += `Steps:\n${skill.steps.map((s, i) => `${i + 1}. ${s}`).join("\n")}\n`;
      context += `Constraints:\n${skill.constraints.map((c) => `- ${c}`).join("\n")}\n\n`;
    }
  }

  if (memories) {
    context += "## Relevant Past Experiences\n\n";
    context += memories + "\n\n";
  }

  if (corrections.length > 0) {
    context += "## Recent Corrections\n\n";
    for (const c of corrections.slice(0, 5)) {
      context += `- Instead of: ${c.agentBehavior}\n  Do: ${c.humanCorrection}\n`;
    }
    context += "\n";
  }

  return context;
}
```

The loop runs on every task execution. Over time, the agent's context becomes enriched with relevant skills, past experiences, and human corrections. Each interaction contributes to the next one.

## Measuring Improvement

Self-improvement claims require measurement. Here are concrete metrics to track.

### First-Attempt Success Rate

Track whether the agent's first attempt at a task is accepted without correction.

```typescript
interface PerformanceMetrics {
  totalTasks: number;
  firstAttemptSuccesses: number;
  correctionsReceived: number;
  averageConfidence: number;
  skillCount: number;
}

function successRate(metrics: PerformanceMetrics): number {
  return metrics.firstAttemptSuccesses / metrics.totalTasks;
}
```

A self-improving agent should show increasing first-attempt success rate over time. If the rate is flat, the memory and skill systems are not being retrieved effectively.

### Correction Frequency Decline

Plot corrections per task over time. A declining trend means the agent is learning from previous corrections and not repeating mistakes.

### Skill Coverage

Track what percentage of tasks have applicable skills in the library. Higher coverage means fewer tasks where the agent operates from base capabilities alone.

## Practical Considerations

### Memory Pruning

Unbounded memory eventually degrades performance. Old, low-confidence reflections add noise without value. Prune aggressively:

- Remove reflections older than 90 days with confidence below 0.5
- Merge similar reflections into consolidated entries
- Archive rather than delete, so you can analyze historical patterns

### Skill Conflicts

When two skills give contradictory advice, the agent needs a resolution strategy. The simplest approach: prefer the skill with higher confidence and more source reflections. A skill based on 30 experiences at 0.9 confidence overrides one based on 3 experiences at 0.6 confidence.

### Human Override

Self-improvement systems must preserve human authority. If a developer explicitly overrides a skill or correction, that override takes precedence. The system should not argue with direct instructions, even if its learned behavior disagrees.

```typescript
interface Override {
  skillName: string;
  originalBehavior: string;
  overrideBehavior: string;
  reason: string;
  permanent: boolean;
}
```

Permanent overrides modify the skill directly. Temporary overrides apply for the current session only. Both are tracked so the agent can distinguish between "the human always wants this" and "the human wanted this once."

## The Compounding Effect

A self-improving agent that runs 20 tasks per day and extracts lessons from 10% of them accumulates 2 new reflections daily. After a month, it has 60 reflections. After six months, 360. These reflections condense into 20 to 40 skills that cover the agent's most common tasks.

The agent after six months of accumulation is fundamentally different from the agent on day one. It has seen the failure modes, learned the conventions, absorbed the corrections, and encoded the solutions. Every session is faster and more accurate than the last.

This is the promise of self-improving AI agents. Not artificial general intelligence. Not consciousness. Just systems that remember what worked, remember what failed, and apply those memories to the next task. The implementation is straightforward. The compounding effect is not.

## FAQ

### What is a self-improving AI agent?

A self-improving AI agent is a system that reflects on its task executions, extracts lessons from successes and failures, stores those lessons in persistent memory, and retrieves them for future tasks. Unlike standard agents that start fresh each session, self-improving agents accumulate knowledge over time and measurably improve their performance.

### How does reflection work in AI agents?

Reflection is a separate evaluation pass after task execution. The agent completes a task, then a second prompt analyzes what happened and extracts transferable lessons. Separating execution from evaluation produces better results for both - the execution pass focuses entirely on the task, while the evaluation pass focuses entirely on analysis.

### What is the best memory architecture for self-improving agents?

It depends on scale. Flat file memory works for agents with fewer than 500 reflections. Structured memory with categories (technical/bugs, process/deployment, etc.) works for diverse tasks across multiple domains. Embedding-based retrieval with vector search is necessary for thousands of reflections or when keyword matching is insufficient.

### How do agents convert reflections into skills?

Skill extraction analyzes multiple related reflections and synthesizes them into a reusable procedure. The process identifies a clear name, ordered steps that work reliably, and constraints (things to avoid based on failures). Skills evolve as new reflections accumulate - a skill based on 5 reflections is rough, while the same skill after 50 reflections is battle-tested.

### How do corrections improve agent behavior?

Corrections are the highest-signal input for self-improvement. When a human corrects an agent, that correction represents a gap between actual and desired behavior. The system categorizes corrections, stores them with confidence decay (recent corrections matter more), and after multiple corrections in the same category, updates the relevant skill.

### How do you measure if an agent is actually improving?

Track three metrics: first-attempt success rate (tasks completed without corrections), correction frequency over time (should decline), and skill coverage (percentage of tasks with applicable skills). A truly self-improving agent shows increasing first-attempt success and declining corrections over weeks and months.

### How much memory should a self-improving agent retain?

Prune aggressively. Remove reflections older than 90 days with confidence below 0.5, merge similar reflections, and archive rather than delete for historical analysis. Unbounded memory eventually degrades performance because old low-confidence reflections add noise without value.

### How do self-improving agents handle conflicting skills?

When two skills give contradictory advice, prefer the skill with higher confidence and more source reflections. A skill based on 30 experiences at 0.9 confidence overrides one based on 3 experiences at 0.6 confidence. Human overrides always take precedence - the system should never argue with direct instructions.


Run AI Models Locally with Ollama and LM Studio
Thu, 09 Apr 2026 00:00:00 GMT

# Run AI Models Locally with Ollama and LM Studio

Running AI models on your own machine gives you something no cloud API can: complete control. No usage limits, no API keys, no data leaving your computer. This guide walks you through setting up both Ollama (CLI-first) and LM Studio (GUI-first), choosing the right models, and integrating local AI into your development workflow.

## Why run models locally?

There are four compelling reasons to run models on your own hardware instead of relying on cloud APIs.

**Privacy.** Your code and prompts never leave your machine. This matters when you are working on proprietary codebases, handling sensitive data, or operating under compliance requirements. Local inference means zero data exposure.

**Cost.** Cloud API calls add up fast. GPT-4 class models cost $10-30 per million tokens. A local model running on your GPU costs nothing per request after the initial hardware investment. If you run hundreds of queries a day, the savings are significant.

**Speed.** No network round trip. Local models respond in milliseconds for short prompts, especially on modern GPUs. You skip DNS lookups, TLS handshakes, queue times, and rate limits entirely.

**Offline access.** Airplanes, coffee shops with bad wifi, network outages - none of these stop a local model. Once downloaded, the model works with zero internet connectivity.

The tradeoff is clear: local models are smaller and less capable than the largest cloud models. But for many tasks - code completion, documentation, refactoring, Q&A - a well-chosen local model is more than sufficient.

## Two tools, two approaches

Before diving in, here is how the two main tools compare:

| Feature | Ollama | LM Studio |
|---------|--------|-----------|
| Interface | CLI + REST API | Desktop GUI + REST API |
| Best for | Developers, scripting, CI/CD | Visual exploration, non-technical users |
| Model format | GGUF (auto-managed) | GGUF (browse and download) |
| Model discovery | `ollama pull ` | Built-in search and download UI |
| API | OpenAI-compatible at :11434 | OpenAI-compatible at :1234 |
| OS support | macOS, Linux, Windows | macOS, Linux, Windows |
| Resource usage | Lightweight daemon | Electron app, heavier footprint |
| Custom models | Modelfile system | Import any GGUF file |

Both tools are free. Most developers end up using Ollama for day-to-day coding workflows and LM Studio for model exploration and testing. You can run both side by side without conflicts since they use different ports.

---

## Part 1: Ollama (CLI-first)

Ollama is the easiest way to run local models from the terminal. It handles model downloads, quantization, memory management, and provides both a CLI and an API server.

### Install Ollama

**macOS:**

```bash
# Install via Homebrew
brew install ollama

# Or download directly from ollama.com
curl -fsSL https://ollama.com/install.sh | sh
```

After installation, Ollama runs as a background service automatically. You can verify it is running:

```bash
ollama --version
```

**Linux:**

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

This installs Ollama and sets up a systemd service. The service starts automatically:

```bash
# Check status
systemctl status ollama

# Start manually if needed
systemctl start ollama
```

For NVIDIA GPU support, make sure you have the NVIDIA Container Toolkit or up-to-date CUDA drivers installed. Ollama detects your GPU automatically.

**Windows:**

Download the installer from [ollama.com/download](https://ollama.com/download). Run the `.exe` and follow the prompts. Ollama runs in the system tray.

For WSL2 users, install the Linux version inside your WSL2 distro instead. This gives you better GPU passthrough and a more consistent development experience.

### Verify the installation

```bash
# Should print the version number
ollama --version

# List downloaded models (empty on fresh install)
ollama list

# The API server runs on port 11434 by default
curl http://localhost:11434/api/tags
```

### Your first model: ollama run llama4

Pull and run a model. Llama 4 is Meta's latest open-weight model and a solid starting point.

```bash
# Pull and start an interactive chat session
ollama run llama4
```

The first run downloads the model (this takes a few minutes depending on your connection). Subsequent runs start instantly since the model is cached locally.

Once the model loads, you get an interactive prompt:

```
>>> What is the time complexity of quicksort?
Quicksort has an average-case time complexity of O(n log n) and a
worst-case time complexity of O(n^2). The worst case occurs when the
pivot selection consistently picks the smallest or largest element,
leading to unbalanced partitions...
```

Type `/bye` to exit the session.

### Useful Ollama commands

```bash
# List all downloaded models
ollama list

# Pull a model without starting a chat
ollama pull qwen3.5-coder:32b

# Remove a model to free disk space
ollama rm llama4

# Show model details (parameters, quantization, size)
ollama show llama4

# Run with a system prompt
ollama run llama4 --system "You are a senior Python developer. Be concise."

# Pipe input from a file
cat bug-report.txt | ollama run llama4 "Summarize this bug report in 3 bullet points"

# Run the API server explicitly (usually auto-started)
ollama serve
```

### Creating custom models with Modelfile

Ollama lets you create custom model configurations using a Modelfile. This is useful for baking in a system prompt, adjusting parameters, or layering fine-tuned weights.

```bash
cat > Modelfile << 'HEREDOC'
FROM qwen3.5-coder:32b
SYSTEM "You are a senior full-stack developer. You write clean, well-tested TypeScript and Python. Be concise. Show code, not explanations."
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
HEREDOC

ollama create my-coder -f Modelfile
ollama run my-coder
```

Your custom model appears in `ollama list` and can be used anywhere you reference a model name - in API calls, tool integrations, and scripts.

---

## Part 2: LM Studio (GUI-first)

LM Studio is a desktop application that lets you discover, download, and run local models through a visual interface. If you prefer clicking over typing, or you want a fast way to compare models side by side, LM Studio is the tool for you.

### Install LM Studio

Download the installer for your platform from [lmstudio.ai](https://lmstudio.ai).

- **macOS:** Download the `.dmg`, drag to Applications, and launch.
- **Windows:** Download the `.exe` installer and run it.
- **Linux:** Download the `.AppImage`, make it executable with `chmod +x`, and run it.

LM Studio requires no additional dependencies. It bundles its own inference engine (based on llama.cpp) and handles GPU detection automatically.

### The LM Studio interface

When you open LM Studio, you see four main sections:

1. **Discover** - Browse and search the Hugging Face model catalog directly from the app. Filter by size, quantization, architecture, and popularity. Click download on any GGUF model to pull it locally.

2. **Chat** - An interactive chat interface where you pick a model from your local library and start a conversation. You can adjust temperature, max tokens, system prompt, and other parameters in real time from the sidebar.

3. **My Models** - Your local model library. Shows all downloaded models with size, quantization level, and last-used date. You can delete models from here to reclaim disk space.

4. **Developer** - The local API server. Toggle it on to expose an OpenAI-compatible API endpoint at `http://localhost:1234/v1`. Any tool or script that works with the OpenAI API can point at this endpoint.

### Downloading your first model

1. Open the **Discover** tab
2. Search for "qwen3.5-coder" or "llama 4"
3. You will see multiple versions of each model - look for GGUF files with Q4_K_M quantization as a good starting point
4. Click the download button next to the version you want
5. Wait for the download to complete (progress bar shows in the app)

LM Studio stores models in `~/.cache/lm-studio/models/` on macOS and Linux, and `C:\Users\\.cache\lm-studio\models\` on Windows.

### Running a model in chat

1. Go to the **Chat** tab
2. Click the model selector dropdown at the top
3. Pick a downloaded model
4. Wait a few seconds for it to load into memory
5. Type your message and press Enter

The sidebar lets you adjust these parameters on the fly:

- **Temperature** - Controls randomness. Use 0.1-0.3 for code, 0.7-1.0 for creative text.
- **Max tokens** - Maximum response length. Set higher for long code generation.
- **System prompt** - Instructions that apply to the whole conversation.
- **Context length** - How much previous conversation the model can see. Higher values use more RAM.
- **GPU offload** - How many layers to run on GPU vs CPU. More GPU layers means faster inference.

### Starting the local API server

The real power of LM Studio for developers is its local API server.

1. Go to the **Developer** tab
2. Select a model to serve
3. Click **Start Server**
4. The server starts at `http://localhost:1234/v1`

You can now call it from any tool or script using the OpenAI API format:

```bash
curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "You are a helpful coding assistant."},
      {"role": "user", "content": "Write a TypeScript function that debounces another function"}
    ],
    "temperature": 0.2
  }'
```

Python example:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="lm-studio",  # required by the library but not checked
)

response = client.chat.completions.create(
    model="local-model",
    messages=[
        {"role": "system", "content": "You are a senior TypeScript developer."},
        {"role": "user", "content": "Explain the builder pattern with an example"},
    ],
    temperature=0.3,
)

print(response.choices[0].message.content)
```

Note: The model name in API calls can be anything when using LM Studio - it routes to whichever model you have loaded in the Developer tab. Some setups use `"local-model"` as a convention.

### Comparing models side by side

One of LM Studio's standout features is the ability to load two models and compare their responses to the same prompt. This is invaluable when deciding which model to use for a specific task.

1. In the Chat tab, click the "+" button to create a new chat
2. Load a different model in this tab
3. Send the same prompt to both
4. Compare quality, speed, and token usage

This visual comparison is something Ollama cannot do without custom scripting.

---

## Best models for coding

Not all models are created equal for programming tasks. Here are the top choices for code generation, completion, and refactoring as of April 2026.

### Qwen 3.5 Coder

The current leader for local code generation. Available in multiple sizes to fit your hardware.

```bash
# 32B parameters - best quality, needs 20GB+ VRAM
ollama run qwen3.5-coder:32b

# 14B - great balance of quality and speed
ollama run qwen3.5-coder:14b

# 7B - fast, works on 8GB VRAM
ollama run qwen3.5-coder:7b
```

Qwen 3.5 Coder excels at:
- Multi-file code generation
- Understanding complex codebases
- TypeScript, Python, Rust, and Go
- Following coding conventions from context

### DeepSeek Coder V3

Strong at code reasoning and multi-step problem solving. Particularly good at debugging.

```bash
# 33B - full quality
ollama run deepseek-coder-v3:33b

# 7B - lightweight option
ollama run deepseek-coder-v3:7b
```

Best for:
- Debugging and error analysis
- Algorithm implementation
- Code review and suggestions
- Mathematical and logical reasoning in code

### CodeLlama

Meta's code-specialized Llama variant. Mature, well-tested, and widely supported by tools.

```bash
# 34B - best quality
ollama run codellama:34b

# 13B - good middle ground
ollama run codellama:13b

# 7B - lightweight
ollama run codellama:7b
```

Best for:
- Code infilling (fill-in-the-middle)
- Large context windows (up to 100K tokens)
- Broad language support
- Integration with older tooling that expects CodeLlama

### Quick comparison for coding models

| Model | Size | VRAM Needed | Speed | Code Quality |
|-------|------|-------------|-------|-------------|
| Qwen 3.5 Coder 32B | 18GB | 24GB | Medium | Excellent |
| Qwen 3.5 Coder 14B | 8GB | 12GB | Fast | Very Good |
| DeepSeek Coder V3 33B | 19GB | 24GB | Medium | Excellent |
| DeepSeek Coder V3 7B | 4GB | 8GB | Very Fast | Good |
| CodeLlama 34B | 19GB | 24GB | Medium | Very Good |
| CodeLlama 7B | 4GB | 8GB | Very Fast | Decent |

## Best models for general use

For chat, writing, summarization, and general reasoning tasks, these models lead the pack.

### Llama 4

Meta's flagship open model. Strong across the board for general tasks.

```bash
# Scout variant - lighter, faster
ollama run llama4

# Maverick variant - larger, more capable
ollama run llama4:maverick
```

### Mistral

Mistral's models punch well above their weight class. Excellent efficiency-to-quality ratio.

```bash
# Mistral Large - top quality
ollama run mistral-large

# Mistral Small - fast and capable
ollama run mistral-small

# Mistral 7B - lightweight classic
ollama run mistral:7b
```

### Phi-4

Microsoft's compact model series. Surprisingly capable for its size.

```bash
# Phi-4 14B - best in class for its size
ollama run phi4:14b
```

### Quick comparison for general models

| Model | Size | VRAM Needed | Speed | Quality |
|-------|------|-------------|-------|---------|
| Llama 4 Scout | 15GB | 20GB | Medium | Excellent |
| Llama 4 Maverick | 25GB | 32GB | Slow | Outstanding |
| Mistral Large | 22GB | 28GB | Medium | Excellent |
| Mistral Small | 8GB | 12GB | Fast | Very Good |
| Phi-4 14B | 8GB | 10GB | Fast | Very Good |

## Using local models with AI coding tools

The real power of local models comes from integrating them into your existing development workflow.

### Claude Code

Claude Code can use local models as a backend through the OpenAI-compatible API that Ollama provides.

```bash
# Set the environment variables to point at your local Ollama
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
```

Or point at LM Studio:

```bash
export OPENAI_API_BASE=http://localhost:1234/v1
export OPENAI_API_KEY=lm-studio
```

You can also configure a model alias in your shell profile:

```bash
# Add to ~/.zshrc or ~/.bashrc
alias claude-local='OPENAI_API_BASE=http://localhost:11434/v1 claude'
```

### Cursor

Cursor has built-in support for local models.

1. Open Cursor Settings (Cmd+Shift+P on macOS, Ctrl+Shift+P on Linux/Windows)
2. Navigate to **Models** > **Model Provider**
3. Select **Ollama** as the provider
4. Choose your model from the dropdown (Cursor auto-detects running models)

Alternatively, configure it in `~/.cursor/settings.json`:

```json
{
  "ai.provider": "ollama",
  "ai.model": "qwen3.5-coder:32b",
  "ai.endpoint": "http://localhost:11434"
}
```

For LM Studio, set the provider to "OpenAI Compatible" and point at `http://localhost:1234/v1`.

### Continue.dev

Continue is an open-source AI coding assistant that runs in VS Code and JetBrains. It has excellent local model support.

Install the Continue extension, then edit `~/.continue/config.yaml`:

```yaml
models:
  - title: "Qwen 3.5 Coder 32B"
    provider: ollama
    model: qwen3.5-coder:32b
    apiBase: http://localhost:11434

  - title: "LM Studio Model"
    provider: lmstudio
    model: local-model
    apiBase: http://localhost:1234

tabAutocompleteModel:
  title: "Qwen Coder 7B"
  provider: ollama
  model: qwen3.5-coder:7b
  apiBase: http://localhost:11434
```

This gives you a full local AI coding setup: the 32B model for chat and generation, and the fast 7B model for tab autocomplete.

### Using the API directly

Both Ollama and LM Studio expose OpenAI-compatible REST APIs. You can call them from any language or tool.

**Ollama (port 11434):**

```bash
curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen3.5-coder:32b",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Explain async/await in JavaScript"}
  ]
}'
```

**LM Studio (port 1234):**

```bash
curl http://localhost:1234/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "local-model",
    "messages": [
      {"role": "system", "content": "You are a helpful coding assistant."},
      {"role": "user", "content": "Explain async/await in JavaScript"}
    ]
  }'
```

Python example using the `openai` library (works with either backend):

```python
from openai import OpenAI

# For Ollama
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

# For LM Studio
# client = OpenAI(
#     base_url="http://localhost:1234/v1",
#     api_key="lm-studio",
# )

response = client.chat.completions.create(
    model="qwen3.5-coder:32b",
    messages=[
        {"role": "system", "content": "You are a senior developer."},
        {"role": "user", "content": "Review this function for bugs"},
    ],
)

print(response.choices[0].message.content)
```

## Performance tips

Getting the best performance out of local models requires understanding a few key concepts.

### Quantization

Models come in different quantization levels that trade quality for speed and memory usage. Both Ollama and LM Studio handle this, but you can choose specific quantizations.

```bash
# Q4_K_M - default, good balance (recommended)
ollama run qwen3.5-coder:32b

# Q8_0 - higher quality, more memory
ollama run qwen3.5-coder:32b-q8_0

# Q2_K - smallest, fastest, lowest quality
ollama run qwen3.5-coder:32b-q2_k
```

In LM Studio, you see the quantization level listed next to each download option. Look for "Q4_K_M" or "Q5_K_M" for the best balance.

| Quantization | Quality | Size (32B model) | Speed |
|-------------|---------|-------------------|-------|
| Q2_K | Decent | ~12GB | Fastest |
| Q4_K_M | Very Good | ~18GB | Fast |
| Q5_K_M | Excellent | ~22GB | Medium |
| Q8_0 | Near-Original | ~34GB | Slow |
| FP16 | Original | ~64GB | Slowest |

For coding tasks, Q4_K_M is the sweet spot. Below Q4, you start seeing noticeable quality degradation in code generation. Q8_0 is worth it if you have the VRAM.

### GPU vs CPU inference

GPU inference is dramatically faster than CPU inference. If you have a dedicated GPU, make sure your tool is using it.

```bash
# Check if Ollama detects your GPU
ollama ps

# Force GPU layers (useful for partial offloading)
OLLAMA_NUM_GPU=999 ollama run llama4
```

In LM Studio, the GPU offload slider in the model settings controls how many layers run on GPU. Set it to the maximum your VRAM allows.

Approximate speed comparison for a 14B model:

| Hardware | Tokens/second | Time for 500-token response |
|----------|--------------|----------------------------|
| NVIDIA RTX 4090 | 80-100 t/s | ~5 seconds |
| NVIDIA RTX 4070 | 40-60 t/s | ~10 seconds |
| Apple M3 Max (GPU) | 30-50 t/s | ~12 seconds |
| Apple M2 Pro (GPU) | 20-35 t/s | ~18 seconds |
| CPU only (modern) | 5-10 t/s | ~60 seconds |

### Memory requirements

The golden rule: you need enough VRAM (or unified memory on Apple Silicon) to fit the entire model. If the model does not fit in VRAM, it spills to system RAM, which is 10-20x slower.

```bash
# Check current memory usage
ollama ps

# Set maximum VRAM usage
OLLAMA_MAX_VRAM=20000 ollama serve  # 20GB limit
```

**Apple Silicon users:** You are in a good position. The unified memory architecture means your GPU can access all system RAM. A MacBook Pro with 36GB of unified memory can run 32B parameter models comfortably.

**NVIDIA users:** Your VRAM is the hard limit. A 24GB RTX 4090 fits most 32B quantized models. For 70B+ models, you need multi-GPU setups or significant CPU offloading.

### Context length optimization

Longer context windows use more memory. If you are running tight on VRAM, reduce the context length.

```bash
# Default context length is 2048
# Increase for larger codebases
ollama run qwen3.5-coder:32b --num-ctx 8192

# Reduce to save memory
ollama run qwen3.5-coder:32b --num-ctx 1024
```

In LM Studio, adjust the "Context Length" slider in the model settings panel before loading a model.

### Running multiple models

Ollama can keep multiple models loaded in memory simultaneously. This is useful when you want a fast small model for autocomplete and a large model for complex tasks.

```bash
# Load two models at once
OLLAMA_MAX_LOADED_MODELS=2 ollama serve
```

LM Studio loads one model at a time in the chat interface but can serve a different model via the API server simultaneously.

## Comparison: local vs cloud API

Neither local nor cloud is universally better. The right choice depends on your specific situation.

### When local models win

- **High-volume usage.** If you send hundreds of requests per day, local inference is essentially free after hardware costs. Cloud APIs charge per token.
- **Privacy requirements.** Regulated industries, proprietary codebases, or personal preference for data sovereignty. Local means no third-party data processing.
- **Offline workflows.** Traveling, unreliable connections, or air-gapped environments.
- **Latency-sensitive tasks.** Tab autocomplete, inline suggestions, and real-time code generation benefit from zero network latency.
- **Predictable costs.** No surprise bills. The hardware cost is fixed regardless of usage.

### When cloud APIs win

- **Maximum capability.** The largest cloud models (Claude, GPT-4.5, Gemini Ultra) are still significantly more capable than anything you can run locally. For complex multi-step reasoning, architectural decisions, or nuanced code review, cloud models have the edge.
- **No hardware investment.** You do not need an expensive GPU. A $20/month API subscription gives you access to frontier models.
- **Always up to date.** Cloud providers update models continuously. Local models require manual pulls and version management.
- **Scale to zero.** Pay only when you use it. If you have light, sporadic usage, cloud APIs are more cost-effective than dedicated hardware.
- **Multi-modal capabilities.** Cloud models increasingly support images, audio, and video inputs that local models cannot match.

### The hybrid approach (recommended)

The best setup for most developers is a hybrid approach:

- **Local model for autocomplete and quick tasks.** Run a fast 7B model for tab completion, inline suggestions, and quick questions. This handles 80% of your daily AI interactions with zero latency and zero cost.
- **Cloud API for complex tasks.** Use Claude or GPT-4.5 for architectural decisions, complex refactoring, multi-file changes, and deep code review. These tasks benefit from the larger model's superior reasoning.

```bash
# Example hybrid setup
# Terminal 1: Ollama running locally for autocomplete
ollama serve

# Terminal 2: LM Studio for model exploration and testing
# (launch the desktop app)

# Terminal 3: Use Claude Code for complex tasks (cloud)
claude

# Your editor: Continue.dev with Ollama for autocomplete,
# cloud model for chat
```

This gives you the best of both worlds: fast, free, private AI for routine tasks, and maximum capability when you need it.

## Troubleshooting

### Ollama is not detecting my GPU

```bash
# Check GPU detection
ollama ps

# On Linux, ensure CUDA drivers are installed
nvidia-smi

# On macOS, Metal support is automatic for Apple Silicon
# Intel Macs do not have GPU acceleration in Ollama
```

### LM Studio shows "out of memory" when loading a model

Your model is too large for your available VRAM. Try:
1. Choose a smaller quantization (Q4 instead of Q8)
2. Reduce the GPU offload slider so more layers run on CPU
3. Lower the context length
4. Close other GPU-intensive applications
5. Choose a smaller model variant (7B instead of 14B)

### Models are slow on first load but fast after

This is normal. The first load reads the model from disk into memory. Subsequent inferences reuse the loaded model. Both Ollama and LM Studio keep models cached in memory until you explicitly unload them or run out of memory.

### API calls return connection refused

Make sure the server is actually running:

```bash
# For Ollama
curl http://localhost:11434/api/tags

# For LM Studio, check the Developer tab - the server toggle must be ON
curl http://localhost:1234/v1/models
```

## Next steps

Now that you have local AI running, here are some ways to go deeper:

- **Explore the model library.** Browse [ollama.com/library](https://ollama.com/library) or LM Studio's Discover tab for hundreds of available models.
- **Create custom models.** Write an Ollama `Modelfile` to create models with custom system prompts and parameters.
- **Set up a team server.** Run Ollama on a shared machine so your whole team can access local models over the network.
- **Try different quantizations.** Experiment with Q4 vs Q8 for your specific use case to find your quality-speed sweet spot.
- **Build with the API.** Use the OpenAI-compatible endpoints from either tool to integrate local AI into your own applications and scripts.

Local AI is not a replacement for cloud models. It is a complement that fills a different niche: fast, private, free, and always available. Set it up once, and it becomes a natural part of your development workflow.


Building Your First MCP Server
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT

# Building Your First MCP Server

MCP (Model Context Protocol) is the standard way to give AI agents access to external tools and data. Instead of building custom integrations for every AI client, you build one MCP server that works with Claude Code, Cursor, Windsurf, and any other MCP-compatible tool.

This guide takes you from zero to a working MCP server in TypeScript. You will build a server that exposes tools, serves resources, and handles prompt templates. By the end, you will have a server you can plug into your AI coding workflow.

## Prerequisites

Before you start, make sure you have:

- **Node.js 18+** installed (`node --version` to check)
- **npm** or another package manager (pnpm, yarn, bun all work)
- **An MCP-compatible client** to test with (Claude Code is recommended)
- **Basic TypeScript knowledge** (types, async/await, imports)

No prior MCP experience is required. This guide explains every concept from scratch.

## What is an MCP server?

An MCP server is a program that exposes three types of capabilities to AI clients:

1. **Tools** - Functions the AI can call. Think of these as API endpoints the model invokes when it needs to take an action: read a database, send an email, create a file, query an API. Tools are the most commonly used MCP capability.

2. **Resources** - Data the AI can read. Resources provide context to the model, like files, database records, or API responses. They are read-only and let the model access information without calling a tool.

3. **Prompt templates** - Reusable prompt structures with placeholders. These help standardize how the AI interacts with your domain by providing pre-built prompts that users can fill in.

The server communicates with clients over one of two transports:

- **Stdio** - The server reads from stdin and writes to stdout. The client spawns the server as a child process. This is the simplest transport and the one most clients use.
- **HTTP/SSE** - The server runs as an HTTP service. Clients connect via Server-Sent Events. This is useful for remote servers, shared team servers, and production deployments.

For this guide, we will use stdio transport since it is simpler and works with the widest range of clients.

## Project setup

Create a new directory and initialize the project:

```bash
mkdir my-mcp-server
cd my-mcp-server
npm init -y
```

Install the MCP SDK and TypeScript:

```bash
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
```

The `@modelcontextprotocol/sdk` package is the official TypeScript SDK for building MCP servers. `zod` is used for defining input schemas for your tools.

Create a `tsconfig.json`:

```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}
```

Update your `package.json` to include the build script and set the module type:

```json
{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "my-mcp-server": "dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
    "start": "node dist/index.js"
  }
}
```

Create the source directory:

```bash
mkdir src
```

## Building the server

### Step 1: Create the server entry point

Create `src/index.ts`. This is the main file that sets up the MCP server, defines its capabilities, and connects the transport.

```typescript
#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Create the MCP server instance
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// We will add tools, resources, and prompts here in the next steps

// Connect using stdio transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});
```

Note that we log to `stderr` (via `console.error`), not `stdout`. This is important because stdout is reserved for the MCP protocol messages. Any logging you do must go to stderr.

### Step 2: Add your first tool

Tools are the core of most MCP servers. Let's add a simple tool that fetches the current weather for a city. This demonstrates the pattern you will use for all tools: define a name, description, input schema, and handler function.

Add this between the server creation and the `main()` function:

```typescript
import { z } from "zod";

server.tool(
  "get_weather",
  "Get the current weather for a city. Returns temperature, conditions, and humidity.",
  {
    city: z.string().describe("The city name, e.g. 'San Francisco'"),
    units: z
      .enum(["celsius", "fahrenheit"])
      .default("celsius")
      .describe("Temperature units"),
  },
  async ({ city, units }) => {
    // In a real server, you would call a weather API here.
    // For this example, we return mock data.
    const temp = units === "celsius" ? 22 : 72;
    const unitLabel = units === "celsius" ? "C" : "F";

    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${temp} degrees ${unitLabel}, partly cloudy, 65% humidity.`,
        },
      ],
    };
  }
);
```

Let's break down the four arguments to `server.tool()`:

1. **Name** (`"get_weather"`) - A unique identifier for the tool. AI clients use this name to call the tool. Use snake_case by convention.

2. **Description** - A natural language explanation of what the tool does. The AI model reads this description to decide when to use the tool. Be specific about inputs, outputs, and when the tool is appropriate.

3. **Input schema** - A Zod schema defining the parameters the tool accepts. The SDK validates inputs against this schema before calling your handler. Zod's `.describe()` method adds parameter-level descriptions that help the AI fill in the right values.

4. **Handler** - An async function that receives the validated inputs and returns a result. The result must include a `content` array with text or image blocks.

### Step 3: Add a tool with error handling

Real tools need error handling. Here is a more realistic tool that reads a file from disk:

```typescript
import fs from "fs/promises";
import path from "path";

server.tool(
  "read_file",
  "Read the contents of a file at the given path. Returns the file content as text. Fails if the file does not exist or cannot be read.",
  {
    filePath: z.string().describe("Absolute or relative path to the file"),
  },
  async ({ filePath }) => {
    try {
      const resolvedPath = path.resolve(filePath);
      const content = await fs.readFile(resolvedPath, "utf-8");

      return {
        content: [
          {
            type: "text",
            text: content,
          },
        ],
      };
    } catch (error) {
      const message =
        error instanceof Error ? error.message : "Unknown error";

      return {
        content: [
          {
            type: "text",
            text: `Error reading file: ${message}`,
          },
        ],
        isError: true,
      };
    }
  }
);
```

Notice the `isError: true` flag in the error response. This tells the AI client that the tool invocation failed, so the model can adjust its approach (try a different path, ask the user for help, etc.) rather than treating the error message as successful output.

### Step 4: Add a tool that calls an external API

Here is a tool that demonstrates calling a real external service - searching a database, calling a REST API, or querying a third-party service:

```typescript
server.tool(
  "search_github_repos",
  "Search GitHub repositories by keyword. Returns the top 5 matching repos with name, description, stars, and URL.",
  {
    query: z.string().describe("Search query for GitHub repositories"),
    language: z
      .string()
      .optional()
      .describe("Filter by programming language, e.g. 'typescript'"),
  },
  async ({ query, language }) => {
    const params = new URLSearchParams({
      q: language ? `${query} language:${language}` : query,
      sort: "stars",
      order: "desc",
      per_page: "5",
    });

    const response = await fetch(
      `https://api.github.com/search/repositories?${params}`,
      {
        headers: {
          Accept: "application/vnd.github.v3+json",
          "User-Agent": "my-mcp-server",
        },
      }
    );

    if (!response.ok) {
      return {
        content: [
          {
            type: "text",
            text: `GitHub API error: ${response.status} ${response.statusText}`,
          },
        ],
        isError: true,
      };
    }

    const data = await response.json();
    const repos = data.items.map(
      (repo: {
        full_name: string;
        description: string | null;
        stargazers_count: number;
        html_url: string;
      }) => ({
        name: repo.full_name,
        description: repo.description || "No description",
        stars: repo.stargazers_count,
        url: repo.html_url,
      })
    );

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(repos, null, 2),
        },
      ],
    };
  }
);
```

### Step 5: Add resources

Resources provide read-only data to the AI client. They are useful for exposing configuration files, database state, or any data the model might need for context.

```typescript
server.resource(
  "config",
  "config://app/settings",
  async (uri) => {
    // In a real server, read from a config file or database
    const config = {
      appName: "My Application",
      version: "2.1.0",
      environment: process.env.NODE_ENV || "development",
      features: {
        darkMode: true,
        notifications: true,
        analytics: false,
      },
    };

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(config, null, 2),
        },
      ],
    };
  }
);
```

The `server.resource()` method takes three arguments:

1. **Name** - A human-readable name for the resource.
2. **URI** - A unique identifier using a custom scheme (like `config://` or `db://`). Clients use this URI to request the resource.
3. **Handler** - An async function that returns the resource contents. The handler receives the parsed URI object.

You can also add resources with dynamic URIs using templates:

```typescript
server.resource(
  "user-profile",
  "users://{userId}/profile",
  async (uri) => {
    // Extract the userId from the URI
    const userId = uri.pathname.split("/")[1];

    // Fetch user data (mock example)
    const user = {
      id: userId,
      name: "Jane Developer",
      email: "jane@example.com",
      role: "admin",
    };

    return {
      contents: [
        {
          uri: uri.href,
          mimeType: "application/json",
          text: JSON.stringify(user, null, 2),
        },
      ],
    };
  }
);
```

### Step 6: Add prompt templates

Prompt templates are reusable prompt structures that help standardize how the AI interacts with your domain. They are optional but useful for common workflows.

```typescript
server.prompt(
  "code_review",
  "Review code for bugs, security issues, and best practices",
  {
    code: z.string().describe("The code to review"),
    language: z.string().describe("Programming language of the code"),
    focus: z
      .enum(["bugs", "security", "performance", "all"])
      .default("all")
      .describe("What to focus the review on"),
  },
  ({ code, language, focus }) => {
    const focusInstructions = {
      bugs: "Focus specifically on bugs, logic errors, and edge cases that could cause failures.",
      security:
        "Focus specifically on security vulnerabilities, injection risks, and unsafe patterns.",
      performance:
        "Focus specifically on performance bottlenecks, unnecessary allocations, and optimization opportunities.",
      all: "Review for bugs, security issues, performance problems, and general best practices.",
    };

    return {
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Review the following ${language} code.\n\n${focusInstructions[focus]}\n\n\`\`\`${language}\n${code}\n\`\`\``,
          },
        },
      ],
    };
  }
);
```

### Step 7: The complete server

Here is the full `src/index.ts` with all the pieces assembled:

```typescript
#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from "fs/promises";
import path from "path";

const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// --- Tools ---

server.tool(
  "get_weather",
  "Get the current weather for a city",
  {
    city: z.string().describe("The city name"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  },
  async ({ city, units }) => {
    const temp = units === "celsius" ? 22 : 72;
    const unitLabel = units === "celsius" ? "C" : "F";
    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${temp} degrees ${unitLabel}, partly cloudy, 65% humidity.`,
        },
      ],
    };
  }
);

server.tool(
  "read_file",
  "Read the contents of a file at the given path",
  {
    filePath: z.string().describe("Path to the file"),
  },
  async ({ filePath }) => {
    try {
      const content = await fs.readFile(path.resolve(filePath), "utf-8");
      return {
        content: [{ type: "text", text: content }],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error: ${error instanceof Error ? error.message : "Unknown error"}`,
          },
        ],
        isError: true,
      };
    }
  }
);

server.tool(
  "search_github_repos",
  "Search GitHub repositories by keyword",
  {
    query: z.string().describe("Search query"),
    language: z.string().optional().describe("Filter by language"),
  },
  async ({ query, language }) => {
    const params = new URLSearchParams({
      q: language ? `${query} language:${language}` : query,
      sort: "stars",
      order: "desc",
      per_page: "5",
    });

    const response = await fetch(
      `https://api.github.com/search/repositories?${params}`,
      {
        headers: {
          Accept: "application/vnd.github.v3+json",
          "User-Agent": "my-mcp-server",
        },
      }
    );

    if (!response.ok) {
      return {
        content: [
          { type: "text", text: `GitHub API error: ${response.status}` },
        ],
        isError: true,
      };
    }

    const data = await response.json();
    const repos = data.items.map(
      (repo: {
        full_name: string;
        description: string | null;
        stargazers_count: number;
        html_url: string;
      }) => ({
        name: repo.full_name,
        description: repo.description || "No description",
        stars: repo.stargazers_count,
        url: repo.html_url,
      })
    );

    return {
      content: [{ type: "text", text: JSON.stringify(repos, null, 2) }],
    };
  }
);

// --- Resources ---

server.resource("config", "config://app/settings", async (uri) => {
  return {
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify(
          {
            appName: "My Application",
            version: "2.1.0",
            environment: process.env.NODE_ENV || "development",
          },
          null,
          2
        ),
      },
    ],
  };
});

// --- Prompt Templates ---

server.prompt(
  "code_review",
  "Review code for bugs, security issues, and best practices",
  {
    code: z.string().describe("The code to review"),
    language: z.string().describe("Programming language"),
  },
  ({ code, language }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `Review the following ${language} code for bugs, security issues, and best practices:\n\n\`\`\`${language}\n${code}\n\`\`\``,
        },
      },
    ],
  })
);

// --- Start ---

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});
```

## Build and test

### Build the server

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `dist/` directory. Make the output executable:

```bash
chmod +x dist/index.js
```

### Test with Claude Code

The fastest way to test your MCP server is with Claude Code. Add it to your project's `.mcp.json` file:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}
```

Replace the path with the actual absolute path to your compiled server.

Start Claude Code in the project directory:

```bash
claude
```

Your MCP tools should appear in the tool list. Ask Claude to use one:

```
use the get_weather tool to check the weather in Tokyo
```

```
search GitHub for the top MCP server repositories written in TypeScript
```

If the tools do not appear, check for errors by running the server manually:

```bash
node dist/index.js
```

Any errors will print to stderr. Common issues:

- Missing `#!/usr/bin/env node` shebang line
- File not executable (run `chmod +x`)
- Module resolution errors (check `tsconfig.json` module settings)
- Missing dependencies (run `npm install`)

### Test with the MCP Inspector

The MCP Inspector is an official debugging tool that lets you interact with your server directly through a web UI.

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

This opens a browser window where you can:

- See all registered tools, resources, and prompts
- Call tools with custom inputs and inspect the responses
- Read resources and verify their output
- Test prompt templates with different parameters

The Inspector is invaluable during development. Use it to verify your server works correctly before connecting it to an AI client.

### Test with Cursor

Add the server to Cursor's MCP configuration. Open `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp-server/dist/index.js"]
    }
  }
}
```

Restart Cursor, and the tools will be available in Agent mode.

## Adding environment variables

Most real MCP servers need API keys, database URLs, or other configuration. Pass these as environment variables in the MCP config:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "WEATHER_API_KEY": "your-api-key-here",
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}
```

Access them in your server code with `process.env`:

```typescript
server.tool(
  "get_real_weather",
  "Get real weather data from the weather API",
  {
    city: z.string().describe("City name"),
  },
  async ({ city }) => {
    const apiKey = process.env.WEATHER_API_KEY;
    if (!apiKey) {
      return {
        content: [
          { type: "text", text: "Error: WEATHER_API_KEY not configured" },
        ],
        isError: true,
      };
    }

    const response = await fetch(
      `https://api.weather.com/v1/current?city=${encodeURIComponent(city)}&key=${apiKey}`
    );

    const data = await response.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);
```

## Publishing and deployment

### Publish to npm

If you want others to use your MCP server, publish it to npm:

1. Make sure `package.json` has the `bin` field set
2. Add a `files` field to include only the dist directory:

```json
{
  "name": "my-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "my-mcp-server": "dist/index.js"
  },
  "files": ["dist"],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build"
  }
}
```

3. Build and publish:

```bash
npm run build
npm publish
```

Users can then configure it in their MCP settings with:

```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}
```

The `npx -y` prefix downloads and runs the package automatically.

### Deploy as an HTTP server

For team-wide or remote access, you can serve your MCP server over HTTP instead of stdio. Replace the transport setup:

```typescript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,
  });
  res.writeHead(200, {
    "Content-Type": "text/event-stream",
    "Cache-Control": "no-cache",
    Connection: "keep-alive",
  });
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(3001, () => {
  console.error("MCP HTTP server running on port 3001");
});
```

Clients connect using the HTTP transport:

```json
{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

## Best practices

### Write clear tool descriptions

The description is the most important part of a tool definition. The AI model reads it to decide when and how to use the tool. Good descriptions include:

- What the tool does in one sentence
- What inputs are required and what format they should be in
- What the output looks like
- When to use this tool vs another tool
- Any limitations or side effects

Bad: `"Search stuff"`

Good: `"Search GitHub repositories by keyword. Returns the top 5 matching repos with name, description, star count, and URL. Use this when the user asks about open-source projects, libraries, or wants to find code repositories."`

### Keep tools focused

Each tool should do one thing well. A tool called `manage_database` that creates tables, runs queries, and manages migrations is hard for the AI to use correctly. Split it into `create_table`, `run_query`, and `run_migration`.

### Validate inputs thoroughly

The Zod schema handles basic type validation, but add your own validation for business logic:

```typescript
server.tool(
  "delete_file",
  "Delete a file at the given path",
  {
    filePath: z.string().describe("Path to the file to delete"),
  },
  async ({ filePath }) => {
    const resolved = path.resolve(filePath);

    // Safety check: prevent deletion outside the project directory
    if (!resolved.startsWith(process.cwd())) {
      return {
        content: [
          {
            type: "text",
            text: "Error: Cannot delete files outside the project directory",
          },
        ],
        isError: true,
      };
    }

    await fs.unlink(resolved);
    return {
      content: [{ type: "text", text: `Deleted ${resolved}` }],
    };
  }
);
```

### Return structured data when possible

JSON responses let the AI extract specific fields and use them in follow-up operations. Plain text responses work for simple outputs, but structured data scales better:

```typescript
// Prefer this
return {
  content: [
    {
      type: "text",
      text: JSON.stringify(
        {
          status: "success",
          filesCreated: 3,
          outputPath: "/tmp/output",
        },
        null,
        2
      ),
    },
  ],
};
```

### Handle errors gracefully

Always return a meaningful error message with `isError: true` rather than throwing an exception. Thrown exceptions crash the tool invocation and give the AI no information about what went wrong. A descriptive error message lets the AI retry with different inputs or ask the user for help.

## Next steps

Now that you have a working MCP server, explore these directions:

- **Browse existing servers.** The [MCP servers repository](https://github.com/modelcontextprotocol/servers) has dozens of production-quality servers you can study and use as references.
- **Add authentication.** For HTTP-based servers, add API key validation or OAuth to control access.
- **Build domain-specific tools.** Create servers for your team's internal tools - Jira, Slack, your production database, deployment pipeline, monitoring dashboards.
- **Use resource subscriptions.** Resources can notify clients when their data changes, enabling real-time context updates.
- **Read the [MCP specification](https://spec.modelcontextprotocol.io/).** The full spec covers advanced features like sampling, logging, and capability negotiation.

MCP is still early but growing fast. Every major AI coding tool now supports it, and the ecosystem of community servers expands weekly. Building your own server is the best way to understand the protocol and create tools that fit your exact workflow.


AI Agent Frameworks Compared: CrewAI vs LangGraph vs AutoGen vs Claude Code
Developers Digest — Thu, 09 Apr 2026 00:00:00 GMT

# AI Agent Frameworks Compared: CrewAI vs LangGraph vs AutoGen vs Claude Code

**Pick your framework in 30 seconds:**

| Your primary need | Best framework |
|-------------------|----------------|
| Stateful workflows with branches and loops | **[LangGraph](#langgraph)** |
| Role-based pipelines (research → write → edit) | **[CrewAI](#crewai)** |
| Multi-agent chat and iterative refinement | **[AutoGen](#autogen)** |
| Operate on a real codebase from the terminal | **[Claude Code](#claude-code)** |

If you are choosing between **coding agents** specifically, skip to [Claude Code vs Cursor vs Codex](/blog/claude-code-vs-cursor-vs-codex-2026). If **cost** is the main constraint, start at [/pricing](/pricing).

---

This guide provides a deep, practical comparison of the four most important agent frameworks in 2026. We cover architecture, code examples, strengths, weaknesses, and concrete guidance on when to pick each one.

**Related decision pages:**

- [LangChain vs Vercel AI SDK](/blog/langchain-vs-vercel-ai-sdk) - TypeScript app frameworks
- [AI tool comparisons hub](/compare) - Side-by-side comparison pages
- [AI coding tools pricing 2026](/blog/ai-coding-tools-pricing-2026) - Cost breakdown

## What is an agent framework?

An agent framework provides the scaffolding for building AI applications that go beyond single prompt-response interactions. At minimum, a framework handles:

- **Agent definition** - Creating agents with specific roles, instructions, and capabilities
- **Tool integration** - Giving agents the ability to call external functions, APIs, and services
- **Orchestration** - Coordinating multiple agents or multi-step workflows
- **Memory** - Maintaining context across steps and conversations
- **Error handling** - Recovering from failures, retrying, and graceful degradation

Without a framework, you end up writing all of this plumbing yourself. Frameworks let you focus on the business logic of your agents rather than the infrastructure.

## Quick comparison

Before diving into each framework, here is a high-level comparison to orient your decision.

| Feature | CrewAI | LangGraph | AutoGen | Claude Code |
|---------|--------|-----------|---------|-------------|
| **Language** | Python | Python, JS/TS | Python, .NET | TypeScript (SDK) / CLI |
| **Architecture** | Role-based crews | Graph-based state machine | Conversation-based groups | Agentic loop + sub-agents |
| **Learning curve** | Low | High | Medium | Low |
| **Multi-agent** | Built-in crew system | Manual graph wiring | GroupChat pattern | Sub-agent spawning |
| **Model support** | Any (via LiteLLM) | Any (via integrations) | Any (via config) | Claude models only |
| **Tool definition** | Decorated functions | Annotated functions | Function schemas | MCP servers + built-in tools |
| **State management** | Automatic crew state | Explicit graph state | Conversation history | Conversation context + memory |
| **Streaming** | Limited | Full support | Limited | Full support |
| **Production readiness** | Growing | Mature | Growing | Production-grade |
| **Best for** | Team simulations, content pipelines | Complex stateful workflows | Research, multi-agent chat | Code generation, dev automation |
| **License** | MIT | MIT | CC-BY-4.0 (code MIT) | Proprietary (SDK open) |

## CrewAI

CrewAI takes a team metaphor and runs with it. You define agents as team members with specific roles (researcher, writer, reviewer), give them tools, and organize them into a "crew" that executes a sequence of tasks. The framework handles delegation, context passing between agents, and result aggregation.

### Architecture

```
[Crew]
  |
  +-- Agent: Researcher (role, goal, tools)
  |     |
  |     +-- Task: "Research the topic"
  |
  +-- Agent: Writer (role, goal, tools)
  |     |
  |     +-- Task: "Write the article"
  |
  +-- Agent: Editor (role, goal, tools)
        |
        +-- Task: "Edit and polish"
```

CrewAI uses a sequential or hierarchical process model. In sequential mode, tasks execute one after another, with each agent's output feeding into the next agent's context. In hierarchical mode, a manager agent delegates tasks to workers and synthesizes results.

### Code example

```python
from crewai import Agent, Task, Crew, Process
from crewai_tools import SerperDevTool

# Define tools
search_tool = SerperDevTool()

# Define agents
researcher = Agent(
    role="Senior Research Analyst",
    goal="Find comprehensive, accurate information about {topic}",
    backstory="You are an experienced researcher with deep expertise "
              "in technology and AI. You excel at finding primary sources "
              "and verifying claims.",
    tools=[search_tool],
    verbose=True,
)

writer = Agent(
    role="Technical Writer",
    goal="Write a clear, engaging article based on the research",
    backstory="You write for a developer audience. You explain complex "
              "topics simply without dumbing them down. You always include "
              "code examples when relevant.",
    verbose=True,
)

reviewer = Agent(
    role="Editor",
    goal="Review the article for accuracy, clarity, and completeness",
    backstory="You have a sharp eye for technical inaccuracies, unclear "
              "explanations, and missing context. You suggest specific edits.",
    verbose=True,
)

# Define tasks
research_task = Task(
    description="Research {topic} thoroughly. Find the latest developments, "
                "key players, technical details, and practical applications. "
                "Cite your sources.",
    expected_output="A detailed research report with sections, key findings, "
                    "and source URLs.",
    agent=researcher,
)

writing_task = Task(
    description="Using the research report, write a 1500-word article about "
                "{topic}. Include an introduction, 3-4 main sections with "
                "code examples, and a conclusion.",
    expected_output="A complete, well-structured article in markdown format.",
    agent=writer,
)

review_task = Task(
    description="Review the article for technical accuracy, clarity, and "
                "completeness. Provide specific suggestions and a final "
                "edited version.",
    expected_output="A list of edits and the final polished article.",
    agent=reviewer,
)

# Create and run the crew
crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, writing_task, review_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff(inputs={"topic": "MCP servers"})
print(result)
```

### Strengths

- **Intuitive mental model.** The crew/role metaphor maps directly to how people think about team collaboration. Non-technical stakeholders can understand the architecture.
- **Low boilerplate.** Getting a multi-agent pipeline running takes less than 50 lines of code. The framework handles context passing, agent coordination, and output formatting.
- **Built-in tool ecosystem.** CrewAI Tools provides ready-made tools for web search, file operations, code execution, and more. You can also wrap any Python function as a tool.
- **Flexible process models.** Sequential, hierarchical, and consensual process types cover most multi-agent patterns without custom orchestration code.
- **Model agnostic.** Works with OpenAI, Anthropic, Google, Ollama, and any provider supported by LiteLLM.

### Weaknesses

- **Limited control flow.** Complex branching logic, conditional execution, and dynamic task creation are harder to express than in graph-based frameworks. You are mostly constrained to linear or tree-shaped workflows.
- **Debugging opacity.** When a crew produces bad output, tracing which agent made the wrong decision and why can be difficult. The verbose mode helps but produces a lot of noise.
- **Token-heavy.** The role/backstory/goal system generates large system prompts for each agent. In long crews, the cumulative token cost can be significant.
- **Python only.** No official TypeScript or JavaScript SDK. If your stack is Node-based, CrewAI is not a natural fit.
- **Relatively new.** The API surface changes frequently between versions. Production deployments need to pin versions carefully.

### When to use CrewAI

Choose CrewAI when you need a multi-agent pipeline with well-defined roles and sequential (or hierarchical) task execution. It excels at content generation pipelines, research workflows, and any task where the "team of specialists" metaphor fits naturally. If you want the fastest path from idea to working multi-agent system, CrewAI is hard to beat.

---

## LangGraph

LangGraph models agent workflows as directed graphs where nodes are processing steps and edges define the flow between them. It is the most flexible framework in this comparison and the one that gives you the most control over execution flow, state management, and error handling.

### Architecture

```
[StateGraph]
  |
  +-- Node: "research" (function)
  |     |
  |     +-- Edge: if needs_more_info -> "research"
  |     +-- Edge: if complete -> "write"
  |
  +-- Node: "write" (function)
  |     |
  |     +-- Edge: -> "review"
  |
  +-- Node: "review" (function)
        |
        +-- Edge: if approved -> END
        +-- Edge: if needs_revision -> "write"
```

LangGraph uses a state machine pattern. You define a state schema, nodes that transform state, and edges (including conditional edges) that determine the next node based on the current state. This makes complex workflows with loops, branches, and dynamic routing straightforward.

### Code example

```python
from typing import TypedDict, Annotated
from langgraph.graph import StateGraph, END
from langchain_anthropic import ChatAnthropic
from langchain_core.messages import HumanMessage, SystemMessage

# Define the state schema
class AgentState(TypedDict):
    topic: str
    research: str
    draft: str
    review_feedback: str
    final_article: str
    revision_count: int

# Initialize the model
model = ChatAnthropic(model="claude-sonnet-4-20250514")

# Define node functions
def research_node(state: AgentState) -> dict:
    messages = [
        SystemMessage(content="You are a thorough research analyst."),
        HumanMessage(
            content=f"Research the topic: {state['topic']}. "
                    f"Provide detailed findings with sources."
        ),
    ]
    response = model.invoke(messages)
    return {"research": response.content}


def write_node(state: AgentState) -> dict:
    context = state.get("review_feedback", "")
    revision_note = (
        f"\n\nPrevious feedback to address:\n{context}"
        if context
        else ""
    )

    messages = [
        SystemMessage(
            content="You are a technical writer for developers."
        ),
        HumanMessage(
            content=f"Write a 1500-word article based on this research:\n\n"
                    f"{state['research']}{revision_note}"
        ),
    ]
    response = model.invoke(messages)
    return {
        "draft": response.content,
        "revision_count": state.get("revision_count", 0) + 1,
    }


def review_node(state: AgentState) -> dict:
    messages = [
        SystemMessage(
            content="You are a strict technical editor. Respond with either "
                    "'APPROVED' followed by the final text, or 'NEEDS_REVISION' "
                    "followed by specific feedback."
        ),
        HumanMessage(content=f"Review this article:\n\n{state['draft']}"),
    ]
    response = model.invoke(messages)

    if "APPROVED" in response.content[:20]:
        return {
            "final_article": response.content.replace("APPROVED", "").strip(),
            "review_feedback": "",
        }
    else:
        return {
            "review_feedback": response.content.replace(
                "NEEDS_REVISION", ""
            ).strip()
        }


# Define routing logic
def should_revise(state: AgentState) -> str:
    if state.get("final_article"):
        return "end"
    if state.get("revision_count", 0) >= 3:
        # Give up after 3 revisions
        return "end"
    return "revise"


# Build the graph
graph = StateGraph(AgentState)

# Add nodes
graph.add_node("research", research_node)
graph.add_node("write", write_node)
graph.add_node("review", review_node)

# Add edges
graph.set_entry_point("research")
graph.add_edge("research", "write")
graph.add_edge("write", "review")

# Conditional edge: review can loop back to write or finish
graph.add_conditional_edges(
    "review",
    should_revise,
    {
        "revise": "write",
        "end": END,
    },
)

# Compile and run
app = graph.compile()

result = app.invoke({
    "topic": "Building MCP servers in TypeScript",
    "research": "",
    "draft": "",
    "review_feedback": "",
    "final_article": "",
    "revision_count": 0,
})

print(result["final_article"])
```

### Strengths

- **Maximum control.** Every aspect of the workflow is explicit: state schema, node functions, routing logic, and error handling. Nothing is hidden or magical.
- **Complex workflows.** Loops, branches, parallel execution, conditional routing, and dynamic node selection are first-class features. If you can draw it as a flowchart, you can build it in LangGraph.
- **Stateful by design.** The explicit state schema makes it easy to inspect, checkpoint, and resume workflows. You can save state to a database and resume later, which is essential for long-running tasks.
- **Streaming support.** Full streaming of intermediate steps and final output. You can show users what each node is doing in real time.
- **Language support.** Official Python and TypeScript/JavaScript SDKs, both production-quality.
- **LangSmith integration.** Built-in tracing and observability through LangSmith (LangChain's monitoring platform). Every node execution, LLM call, and state transition is logged and inspectable.

### Weaknesses

- **Steep learning curve.** The graph/state-machine paradigm is powerful but takes time to internalize. Simple tasks that take 10 lines in CrewAI require 50+ lines in LangGraph.
- **Verbose boilerplate.** State schemas, node functions, edge definitions, and compilation add significant code overhead for simple workflows.
- **LangChain dependency.** LangGraph is part of the LangChain ecosystem. While it works standalone, the most useful integrations pull in LangChain dependencies. If you have opinions about LangChain, those opinions apply here too.
- **Over-engineering risk.** The flexibility of graphs makes it tempting to build overly complex workflows. Simple sequential pipelines do not need conditional edges and state machines.
- **Documentation density.** The docs are comprehensive but dense. Finding the right pattern for your use case can take digging.

### When to use LangGraph

Choose LangGraph when your workflow has complex control flow - loops, branches, conditional execution, parallel paths, or human-in-the-loop checkpoints. It is the right choice for production systems where you need explicit state management, observability, and the ability to resume failed workflows. If your workflow is simple and sequential, LangGraph is overkill.

---

## AutoGen

AutoGen (by Microsoft) models multi-agent systems as conversations between agents. Instead of defining a graph or a task pipeline, you create agents and put them in a group chat where they talk to each other to solve problems. The framework handles turn-taking, message routing, and termination.

### Architecture

```
[GroupChat]
  |
  +-- Agent: Assistant (LLM-based)
  |     "I'll write the code."
  |
  +-- Agent: Critic (LLM-based)
  |     "Here are issues with the code."
  |
  +-- Agent: Executor (code execution)
  |     "I ran it. Here's the output."
  |
  +-- Agent: UserProxy (human-in-the-loop)
        "Looks good, proceed."
```

AutoGen's conversation-based approach is natural for tasks that benefit from debate, critique, and iterative refinement. Agents exchange messages in a shared conversation, and a speaker-selection mechanism determines who speaks next.

### Code example

```python
from autogen import (
    AssistantAgent,
    UserProxyAgent,
    GroupChat,
    GroupChatManager,
)

# Configuration for the LLM
llm_config = {
    "config_list": [
        {
            "model": "claude-sonnet-4-20250514",
            "api_key": "your-api-key",
            "api_type": "anthropic",
        }
    ],
    "temperature": 0.3,
}

# Define agents
coder = AssistantAgent(
    name="Coder",
    system_message=(
        "You are a senior software engineer. You write clean, well-tested "
        "TypeScript code. When asked to build something, provide complete, "
        "runnable code. Always include error handling."
    ),
    llm_config=llm_config,
)

reviewer = AssistantAgent(
    name="Reviewer",
    system_message=(
        "You are a code reviewer. You examine code for bugs, security "
        "issues, performance problems, and adherence to best practices. "
        "Be specific in your feedback. When the code is good, say APPROVED."
    ),
    llm_config=llm_config,
)

tester = AssistantAgent(
    name="Tester",
    system_message=(
        "You are a QA engineer. You write unit tests for the code provided. "
        "Use vitest for TypeScript tests. Aim for edge cases and error "
        "conditions, not just happy paths."
    ),
    llm_config=llm_config,
)

# UserProxy executes code and provides human input
user_proxy = UserProxyAgent(
    name="UserProxy",
    human_input_mode="TERMINATE",
    max_consecutive_auto_reply=10,
    code_execution_config={
        "work_dir": "workspace",
        "use_docker": False,
    },
)

# Create group chat
group_chat = GroupChat(
    agents=[user_proxy, coder, reviewer, tester],
    messages=[],
    max_round=15,
    speaker_selection_method="auto",
)

manager = GroupChatManager(
    groupchat=group_chat,
    llm_config=llm_config,
)

# Start the conversation
user_proxy.initiate_chat(
    manager,
    message=(
        "Build a TypeScript CLI tool that converts CSV files to JSON. "
        "It should handle headers, quoted fields, and custom delimiters. "
        "Include error handling for malformed input."
    ),
)
```

### Strengths

- **Natural conversation flow.** The group chat pattern feels intuitive for tasks that benefit from discussion, debate, and iterative refinement. Agents naturally build on each other's contributions.
- **Code execution.** Built-in support for running code in sandboxed environments (Docker or local). Agents can write code, execute it, see the output, and fix issues in a loop.
- **Human-in-the-loop.** The UserProxy agent makes it easy to insert human approval, feedback, or corrections at any point in the conversation.
- **Flexible speaker selection.** The framework can automatically decide which agent should speak next based on the conversation context, or you can define explicit turn-taking rules.
- **Microsoft ecosystem.** Deep integration with Azure OpenAI, and strong support from Microsoft Research. Active development and regular releases.

### Weaknesses

- **Unpredictable execution.** The conversation-based approach means you do not always know how many turns a task will take or which agent will handle what. This makes cost estimation and timeout management harder than in deterministic frameworks.
- **Token cost.** Every agent sees the full conversation history. With 4 agents and 15 rounds, the context grows rapidly. Long conversations can burn through tokens fast.
- **Limited structure.** There is no built-in concept of "tasks" or "workflow steps." The structure emerges from the conversation, which can be both a strength (flexibility) and a weakness (unpredictability).
- **Speaker selection issues.** The auto speaker selection sometimes picks the wrong agent or gets stuck in loops. Custom speaker selection functions help but add complexity.
- **Setup complexity.** Configuration objects, agent definitions, and execution environments have many options. Getting the right configuration for your use case takes experimentation.

### When to use AutoGen

Choose AutoGen when your problem benefits from iterative discussion between agents - code generation with review cycles, research with fact-checking, or any task where agents need to debate and refine each other's work. It is particularly strong for code-generation workflows where agents write, test, review, and fix code in a conversational loop. If you need deterministic, repeatable workflows, look elsewhere.

---

## Claude Code

Claude Code is different from the other three frameworks. It is not a library you import into your code - it is a complete AI coding agent that runs in your terminal (or IDE, or web browser). You interact with it through natural language, and it reads your codebase, edits files, runs commands, and manages git operations.

What makes Claude Code relevant as an "agent framework" is its sub-agent system. You can spawn multiple Claude Code instances as sub-agents, each working on a separate task in parallel, coordinated by a parent agent. Combined with MCP servers for external tool integration and hooks for lifecycle automation, Claude Code functions as a full agent orchestration system.

### Architecture

```
[Claude Code - Parent Agent]
  |
  +-- Sub-Agent: "Research the API docs"
  |     (reads files, searches web, returns summary)
  |
  +-- Sub-Agent: "Write the implementation"
  |     (edits files, runs tests, fixes errors)
  |
  +-- Sub-Agent: "Update the documentation"
  |     (reads code changes, updates README and docs)
  |
  +-- MCP Server: Database (query, insert, update)
  +-- MCP Server: Deployment (deploy, rollback, status)
  +-- Hooks: pre-commit linter, post-edit test runner
```

### Code example (SDK usage)

While Claude Code is primarily a CLI tool, the Claude Code SDK lets you use it programmatically in TypeScript:

```typescript
import { ClaudeCode } from "@anthropic-ai/claude-code";

const claude = new ClaudeCode();

// Simple one-shot task
const result = await claude.run({
  prompt: "Add input validation to the signup form in src/components/SignupForm.tsx",
  workingDirectory: "/path/to/project",
});

console.log(result.output);

// Multi-step workflow with sub-agents
async function buildFeature(featureDescription: string) {
  // Step 1: Research
  const research = await claude.run({
    prompt: `Analyze the current codebase and determine the best approach for: ${featureDescription}. Do not make any changes. Return a plan.`,
    workingDirectory: "/path/to/project",
  });

  // Step 2: Implement (using the research as context)
  const implementation = await claude.run({
    prompt: `Implement this feature based on the following plan:\n\n${research.output}\n\nWrite the code, run the tests, and fix any failures.`,
    workingDirectory: "/path/to/project",
  });

  // Step 3: Review
  const review = await claude.run({
    prompt: "Review all changes made in the last commit. Check for bugs, security issues, and missing test coverage. Fix any issues you find.",
    workingDirectory: "/path/to/project",
  });

  return { research, implementation, review };
}

const result = await buildFeature("Add dark mode support with system preference detection");
```

### CLI workflow example

Most Claude Code usage happens interactively in the terminal:

```bash
# Start a session
cd ~/my-project
claude

# Inside the session, use natural language:
# "Add a rate limiter to the API endpoints"
# "Write tests for the payment module and fix any failures"
# "Refactor the auth middleware to use the new session system"

# Or use non-interactive mode for scripting:
claude -p "Add TypeScript strict mode to this project and fix all type errors"

# Spawn sub-agents for parallel work:
# (Inside a Claude Code session)
# "Parallelize this: research the Stripe API, write the webhook handler,
#  and update the docs - use sub-agents for each task"
```

### Strengths

- **Zero boilerplate.** No framework setup, no agent definitions, no state schemas. Point it at a codebase and describe what you want.
- **Full codebase understanding.** Claude Code reads your entire project - files, imports, dependencies, git history, tests. It has context that API-based frameworks cannot match.
- **Real tool execution.** It actually runs commands, edits files, and verifies its work by running tests. This is not simulated tool use - it is real system interaction.
- **MCP integration.** Connect any MCP server to extend Claude Code's capabilities. Database access, deployment pipelines, monitoring dashboards - all available as tools.
- **Sub-agent parallelism.** Spawn multiple agents working on different tasks simultaneously. A parent agent coordinates and synthesizes the results.
- **Hooks system.** Automate pre/post actions: run linters before commits, execute tests after edits, trigger deployments after merges.
- **Cross-platform.** CLI, VS Code, JetBrains, desktop app, web interface, Slack, GitHub Actions - same agent, same config, multiple surfaces.

### Weaknesses

- **Claude-only.** Locked to Anthropic's Claude models. You cannot swap in GPT, Gemini, or open-source models. If Claude goes down or Anthropic changes pricing, you have no fallback.
- **Not a library.** You cannot embed Claude Code's agent logic into your own Python or Node application the way you can with CrewAI or LangGraph. The SDK gives you programmatic access but not framework-level control over the agent loop.
- **Cost.** Claude Code uses Claude models, which are not free. Heavy usage on Max plan ($200/month) or API billing can get expensive compared to running open-source models with other frameworks.
- **Less customizable orchestration.** You describe what you want in natural language. You cannot define explicit state machines, conditional edges, or custom routing logic the way you can in LangGraph.
- **Subscription required.** Requires a Claude Pro, Max, Teams, or Enterprise subscription, or Anthropic API credits.

### When to use Claude Code

Choose Claude Code when your primary task is software development - writing code, fixing bugs, refactoring, adding features, managing git. It is the most capable coding agent available and requires zero framework setup. For multi-agent orchestration beyond coding (content pipelines, data processing, business workflows), pair it with one of the other frameworks or use the SDK to build custom orchestration.

---

## Decision framework

Use this flowchart to pick the right framework for your project.

**Start here: What is your primary task?**

**If code generation and development automation:**
- Use **Claude Code**. It understands codebases natively, runs real commands, and requires no setup. For complex multi-repo orchestration, add the SDK.

**If content/research pipeline with defined roles:**
- Use **CrewAI**. The crew metaphor maps perfectly to content workflows where specialists hand off work in sequence. Fastest time to working prototype.

**If complex stateful workflow with branches and loops:**
- Use **LangGraph**. When you need explicit control over execution flow, state checkpointing, conditional routing, and resumable workflows, LangGraph is the only choice that gives you full control.

**If iterative refinement through debate/critique:**
- Use **AutoGen**. When agents need to discuss, critique, and iteratively improve each other's work, the conversation-based model is the most natural fit.

**If you need multiple frameworks:**
- This is common and fine. Use Claude Code for the coding tasks and CrewAI or LangGraph for the orchestration layer. They are not mutually exclusive.

## Combining frameworks

In practice, production systems often combine frameworks. Here are patterns that work well:

**Claude Code + LangGraph:** Use LangGraph to define the overall workflow (research, implement, test, deploy) and spawn Claude Code sub-agents for the coding steps. LangGraph handles state management and routing; Claude Code handles the actual development.

**CrewAI + Claude Code:** Use a CrewAI crew for content generation (research, write, edit) and trigger Claude Code to implement any code examples or build any tools referenced in the content.

**LangGraph + AutoGen:** Use LangGraph for the high-level workflow graph and AutoGen group chats within specific nodes where agents need to discuss and iterate.

## Final comparison

| Dimension | CrewAI | LangGraph | AutoGen | Claude Code |
|-----------|--------|-----------|---------|-------------|
| **Time to prototype** | Hours | Days | Hours | Minutes |
| **Production readiness** | Medium | High | Medium | High |
| **Debugging experience** | Fair | Good | Fair | Good |
| **Cost at scale** | Varies by model | Varies by model | Varies by model | Claude pricing |
| **Community size** | Large, growing | Large, mature | Large, growing | Very large |
| **Documentation** | Good | Dense but thorough | Improving | Excellent |
| **TypeScript support** | No | Yes | No (Python/.NET) | Native |
| **Custom model support** | Yes (any) | Yes (any) | Yes (any) | No (Claude only) |
| **Determinism** | Low-Medium | High | Low | Low-Medium |
| **Max complexity** | Medium | Very High | Medium | High |

There is no universally "best" framework. Each one reflects a different philosophy about how agents should work. CrewAI says agents are team members. LangGraph says agents are nodes in a graph. AutoGen says agents are participants in a conversation. Claude Code says the agent is your pair programmer.

Pick the philosophy that matches your problem, and you will build faster with fewer headaches.

## Next steps

- **[CrewAI docs](https://docs.crewai.com/)** - Official documentation and tutorials
- **[LangGraph docs](https://langchain-ai.github.io/langgraph/)** - Tutorials, how-to guides, and API reference
- **[AutoGen docs](https://microsoft.github.io/autogen/)** - Getting started and advanced patterns
- **[Claude Code docs](https://docs.anthropic.com/en/docs/claude-code)** - Setup, configuration, and best practices
- **[AI Agents Explained](/blog/ai-agents-explained)** - Foundations of how AI agents work
- **[Multi-Agent Systems](/blog/multi-agent-systems)** - Deep dive into multi-agent architectures
- **[Building Your First MCP Server](/guides/building-your-first-mcp-server)** - Build tools that any MCP-compatible agent can use


AI Agent Memory Patterns
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
Every AI agent starts with amnesia. The context window is its entire working memory, and it resets to zero between sessions. Building useful agents means solving this problem.

Here are the memory patterns that work in production.

## Pattern 1: File-Based Persistence (CLAUDE.md)

The simplest memory system. Write what matters to a file. Read it at the start of every session.

For the larger agent workflow map, read [AI Agents Explained: A TypeScript Developer's Guide](/blog/ai-agents-explained) and [How to Build AI Agents in TypeScript](/blog/how-to-build-ai-agents-typescript); they give the architecture and implementation context this piece assumes.

```typescript
// Write memory
async function remember(key: string, value: string) {
  const memory = JSON.parse(await fs.readFile("memory.json", "utf-8").catch(() => "{}"));
  memory[key] = { value, timestamp: Date.now() };
  await fs.writeFile("memory.json", JSON.stringify(memory, null, 2));
}

// Read memory
async function recall(): Promise> {
  const memory = JSON.parse(await fs.readFile("memory.json", "utf-8").catch(() => "{}"));
  return Object.fromEntries(Object.entries(memory).map(([k, v]: [string, any]) => [k, v.value]));
}
```

[Claude Code](/blog/what-is-claude-code-complete-guide-2026) uses this pattern with CLAUDE.md. Project rules, architecture decisions, coding standards - all persisted as plain text that the model reads at session start.

**When to use:** Project configuration, coding standards, persistent rules. Anything that does not change often but must be remembered across sessions.

**Limitation:** File size is limited by the context window. A 50KB CLAUDE.md consumes tokens that could be used for reasoning. Run yours through our [token estimator](/token-counter) if you are not sure how much headroom you have left.

## Pattern 2: RAG (Retrieval-Augmented Generation)

Instead of loading everything into context, index your knowledge and retrieve only what is relevant to the current query.

```typescript
import { pipeline } from "@huggingface/transformers";

const embedder = await pipeline("feature-extraction", "mixedbread-ai/mxbai-embed-xsmall-v1");

// Index documents
async function index(docs: { id: string; text: string }[]) {
  const vectors = await Promise.all(
    docs.map(async (doc) => {
      const embedding = await embedder(doc.text, { pooling: "mean", normalize: true });
      return { id: doc.id, text: doc.text, vector: embedding.tolist()[0] };
    })
  );
  return vectors;
}

// Retrieve relevant docs for a query
async function retrieve(query: string, index: any[], topK = 3) {
  const queryVec = (await embedder(query, { pooling: "mean", normalize: true })).tolist()[0];

  return index
    .map((doc) => ({
      ...doc,
      score: cosineSimilarity(queryVec, doc.vector),
    }))
    .sort((a, b) => b.score - a.score)
    .slice(0, topK);
}
```

The agent gets relevant context without the full knowledge base consuming the window.

**When to use:** Large knowledge bases (documentation, codebases, conversation history). When the context window cannot hold everything.

**Limitation:** Retrieval quality depends on embedding model and chunking strategy. Bad retrieval means bad context.

## Pattern 3: Conversation Summarization

Long conversations overflow the context window. Instead of dropping old messages, summarize them.

```typescript
async function summarizeHistory(messages: Message[]): Promise {
  if (messages.length < 20) return ""; // No need to summarize short conversations

  const oldMessages = messages.slice(0, -10); // Keep last 10 intact
  const { text } = await generateText({
    model: anthropic("claude-haiku-4-5"),
    prompt: `Summarize this conversation history in 3-5 bullet points. Focus on decisions made, tasks completed, and current state:\n\n${oldMessages.map((m) => `${m.role}: ${m.content}`).join("\n")}`,
  });

  return text;
}

// Use in agent loop
const summary = await summarizeHistory(messages);
const contextMessages = [
  { role: "system", content: `Previous conversation summary:\n${summary}` },
  ...messages.slice(-10), // Recent messages in full
];
```

The agent retains awareness of the full conversation without the token cost.

**When to use:** Long-running agent sessions. Customer support agents. Multi-turn development sessions.

## Pattern 4: Structured State

Track agent state as a typed object, not free text. Serialize between sessions.

```typescript
interface AgentState {
  task: string;
  status: "planning" | "executing" | "reviewing" | "done";
  filesModified: string[];
  testsRun: { file: string; passed: boolean }[];
  decisions: { what: string; why: string; timestamp: number }[];
  blockers: string[];
}

const initialState: AgentState = {
  task: "",
  status: "planning",
  filesModified: [],
  testsRun: [],
  decisions: [],
  blockers: [],
};

// Persist between steps
async function saveState(state: AgentState) {
  await fs.writeFile(".agent-state.json", JSON.stringify(state, null, 2));
}

async function loadState(): Promise {
  return JSON.parse(
    await fs.readFile(".agent-state.json", "utf-8").catch(() => JSON.stringify(initialState))
  );
}
```

The agent can resume exactly where it left off. Every decision is logged with reasoning.

**When to use:** Multi-step workflows that may be interrupted. CI/CD pipelines. Long-running automation.

## Pattern 5: Tiered Memory

Different types of information need different retention strategies.

```
Working Memory (context window)
  - Current task, recent messages, active file contents
  - Lifetime: current session only

Short-Term Memory (session state file)
  - Files modified, tests run, decisions made
  - Lifetime: current task

Long-Term Memory (CLAUDE.md / RAG index)
  - Project rules, architecture, coding standards
  - Lifetime: permanent, updated occasionally

Episodic Memory (conversation logs)
  - Past conversations summarized
  - Lifetime: retained as summaries, raw logs archived
```

Each tier has different storage, retrieval, and eviction strategies.

## Which Pattern to Use

| Scenario | Pattern |
|----------|---------|
| Project configuration | File-based (CLAUDE.md) |
| Large documentation | RAG |
| Long conversations | Summarization |
| Multi-step workflows | Structured state |
| Production agents | Tiered (all of the above) |

Most production agents use a combination. CLAUDE.md for rules + [RAG](/blog/what-is-rag) for knowledge + summarization for history + structured state for workflow tracking.

## Frequently Asked Questions

### Does Claude Code have built-in memory?

Yes. CLAUDE.md files at project, user, and global levels provide persistent memory. Claude Code also has auto-memory that saves important context automatically. But these are file-based - not RAG or semantic search.

### How much context should I reserve for memory vs reasoning?

Keep memory under 30% of the context window. A 200K token window should use at most 60K for memory/context, leaving 140K for reasoning and tool outputs.

### Can I use a vector database for agent memory?

Yes. Pinecone, Weaviate, Chroma, and pgvector all work. For browser-based agents, Transformers.js can compute embeddings client-side. The key is matching the retrieval strategy to your query patterns.

### What is the best chunking strategy for RAG?

For code: chunk by function/class. For documentation: chunk by section (h2 headings). For conversations: chunk by topic shift. Overlapping chunks (50-100 token overlap) improve retrieval accuracy at the boundaries.

## Related apps

- [Agent Eval Bench Plus](https://agenteval.developersdigest.tech/pricing) - Evaluation harness for AI coding agents. Plus tier adds private benchmarks, CI hooks, and historical comparisons.
- [Skill Builder](https://skill.developersdigest.tech) - Build, test, and iterate agent skills from the terminal. Create Claude Code skills with interview or one-liner.

## Related

- [Subscribe to DevDigest on YouTube](https://www.youtube.com/@DevelopersDigest?sub_confirmation=1) for hands-on walkthroughs


Anthropic vs OpenAI: Developer Experience Compared
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
I build with both platforms daily. Anthropic for [Claude Code](/blog/what-is-claude-code-complete-guide-2026) and the Messages API. OpenAI for GPT-5 family models and [Codex](/blog/openai-codex-guide). They have different strengths and the developer experience reflects different design philosophies. If you are at the agent-CLI choice rather than the raw-API choice, our [AI coding agent picker](/which-tool) will narrow the field in a minute.

Source check: keep the official [Anthropic API docs](https://docs.anthropic.com/en/api/overview), [Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/overview), [OpenAI API docs](https://developers.openai.com/api/docs/), and [Codex changelog](https://developers.openai.com/codex/changelog/) open while comparing. If your main question is budget rather than API shape, start with the [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison) and the [pricing calculator](/pricing).

## Read This Alongside

This article is the platform-level comparison. The tool-specific questions branch into nearby posts:

| Question | Best next read |
|----------|----------------|
| Which coding agent should I use day to day? | [Claude Code vs Codex vs Cursor vs OpenCode](/blog/claude-code-vs-codex-vs-cursor-vs-opencode) |
| What changed recently on the OpenAI side? | [Codex changelog April 2026](/blog/codex-changelog-april-2026) |
| How should I budget the tools? | [AI coding tools pricing comparison](/blog/ai-coding-tools-pricing-comparison) |
| How do MCP and tool connections affect platform choice? | [Complete MCP server guide](/blog/complete-guide-mcp-servers) |
| When should I choose Claude-specific workflows? | [Why skills beat prompts](/blog/why-skills-beat-prompts-for-coding-agents-2026) |

The short version: OpenAI versus Anthropic is no longer just a model benchmark. It is also a question of agent surface, tool protocol, [pricing](/blog/ai-coding-tools-pricing-2026) shape, and how much of your workflow you want inside one vendor's product.

## API Design

**Anthropic Messages API** is minimal. One endpoint, one format. Messages go in, a response comes out. Streaming, [tool use](/blog/tool-use-claude-api-production-patterns), and vision all work through the same interface.

For broader context, pair this with the [OpenAI Codex guide](/blog/openai-codex-guide) and [OpenAI vs Anthropic in 2026 - Models, Tools, and Developer Experience](/blog/openai-vs-anthropic-2026); those companion pieces show where this fits in the wider AI developer workflow.

```typescript
const response = await anthropic.messages.create({
  model: "claude-sonnet-4-6",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Explain TypeScript generics" }],
});
```

**OpenAI Chat Completions API** has a similar structure but more options. Response formats, [function calling](/blog/mcp-vs-function-calling) syntax, and streaming modes have evolved through multiple iterations.

```typescript
const response = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Explain TypeScript generics" }],
});
```

Both work well. Anthropic's API has fewer surprises because it has had fewer breaking changes. OpenAI's API has more features but the migration path from GPT-3 to GPT-4 to GPT-5 has required code changes.

## SDKs

| | Anthropic | OpenAI |
|---|---|---|
| TypeScript | `@anthropic-ai/sdk` | `openai` |
| Python | `anthropic` | `openai` |
| Streaming | Native async iterators | Native async iterators |
| Type safety | Full | Full |
| Bundle size | Smaller | Larger |

Both SDKs are well-maintained and fully typed. The Anthropic SDK is leaner. The OpenAI SDK covers more products (DALL-E, Whisper, Assistants, Realtime).

## Coding Tools

This is where the gap is widest.

**Anthropic: Claude Code** is a terminal-native agent that reads your codebase, makes multi-file changes, runs tests, and commits. It has [sub-agents](/blog/claude-code-sub-agents) for parallel work, [MCP](/blog/complete-guide-mcp-servers) for tool integration, hooks for automation, and CLAUDE.md for persistent memory. It is the most capable AI coding tool available.

**OpenAI: Codex** is a cloud-based coding agent. You connect a repo, describe a task, and it works asynchronously in a sandboxed environment. It is powerful but less hands-on than Claude Code, and the recent [Codex April changelog](/blog/codex-changelog-april-2026) shows OpenAI pushing it toward a broader agent workspace. You review results after the fact rather than collaborating in real time.

For daily development, Claude Code is more integrated into the workflow. For large async tasks, Codex has merit.

For the dedicated tool comparison, read [Claude Code vs Codex](/blog/claude-code-vs-codex-app-2026), then check [Codex changelog April 2026](/blog/codex-changelog-april-2026) for the latest OpenAI-side product changes covered here.

## Documentation

**Anthropic** docs are clear and focused. The Claude Code docs are particularly good - practical, well-organized, with real examples. The API docs are straightforward.

**OpenAI** docs are comprehensive but can be overwhelming. There are many products, many API versions, and the Assistants API / Realtime API add complexity. The cookbook has good examples.

## Pricing

| | Anthropic | OpenAI |
|---|---|---|
| Best model | Opus 4.7 ($5/$25 per M) | GPT-5.5 long context ($5/$22.50 per M) |
| Fast model | Sonnet 4.6 ($3/$15 per M) | GPT-5.4 long context ($2.50/$11.25 per M) |
| Cheap model | Haiku 4.5 ($1/$5 per M) | GPT-5.4-mini short context ($0.375/$2.25 per M) |
| Coding tool | Claude Code (Max starts at $100/mo) | Codex pricing varies by plan and model |

OpenAI is usually cheaper on fast and small-model tiers, while flagship pricing is now close enough that context length, cache usage, and output volume matter. Check the [Anthropic pricing page](https://www.anthropic.com/pricing) and [OpenAI API pricing](https://developers.openai.com/api/docs/pricing) for current rates.

## Context Windows

Anthropic leads on the breadth of long-context Claude models. Opus 4.7 and Sonnet 4.6 support 1M tokens, while GPT-5.5 also publishes a 1M-token context window on the OpenAI side. The practical difference is less about the headline limit and more about which model tier you can afford to run at that size.

For large codebase analysis and long-document work, both platforms handle it well at the premium tier.

## The Bottom Line

**Choose Anthropic when:** You want the best [coding agent](/blog/what-is-an-ai-coding-agent-2026) (Claude Code), need large context windows, prefer a simpler API, or value the CLAUDE.md memory system.

**Choose OpenAI when:** You need multimodal capabilities (DALL-E, Whisper, Realtime), want cheaper token pricing, or your team is already invested in the OpenAI ecosystem.

**Use both when:** You are building a production application that benefits from model diversity. Use the Vercel AI SDK to swap providers with a single import change.

## Frequently Asked Questions

### Which has better TypeScript support?

Both SDKs are fully typed. Anthropic's is leaner. OpenAI's covers more products. For pure chat/completion work, they are equivalent.

### Can I use both in the same project?

Yes. The Vercel AI SDK provides a unified interface. Switch between `anthropic("claude-sonnet-4-6")` and `openai("gpt-5.5")` by changing the model string.

### Which is better for building AI agents?

Anthropic, primarily because of Claude Code and the Claude Agent SDK. OpenAI's Assistants API is capable but more complex to set up for agent workflows.

### Which has better rate limits?

OpenAI has more generous free tier limits. Anthropic's paid tiers are more straightforward. For production usage, both require paid plans with adequate limits.

## Related apps

- [Migrate](https://migrate.developersdigest.tech) - OpenAI Assistants API is sunsetting August 26 2026. Paste your code, get Responses API equivalent. Built for the migration deadline.
- [Hookyard Pro](https://hookyard.developersdigest.tech/pricing) - Premium hooks library and config builder for Claude Code. Pro hooks, private bundles, team sync.

## Related

- [Subscribe to DevDigest on YouTube](https://www.youtube.com/@DevelopersDigest?sub_confirmation=1) for hands-on walkthroughs

---

## Sources

- [Anthropic API Documentation](https://docs.anthropic.com/en/api/overview) - Official API reference for Claude models
- [OpenAI API Documentation](https://developers.openai.com/api/docs/) - Official API reference for GPT models
- [OpenAI Models Documentation](https://developers.openai.com/api/docs/models) - Official GPT model reference
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code/overview) - Official Claude Code features and usage
- [Codex CLI Documentation](https://developers.openai.com/codex/cli) - Official OpenAI Codex documentation
- [Codex Changelog](https://developers.openai.com/codex/changelog/) - Latest Codex product updates
- [Anthropic Pricing](https://www.anthropic.com/pricing) - Claude API and subscription pricing
- [OpenAI API Pricing](https://developers.openai.com/api/docs/pricing) - GPT model API rates
- [Anthropic Python SDK](https://github.com/anthropics/anthropic-sdk-python) - Official Python SDK repository
- [OpenAI Python SDK](https://github.com/openai/openai-python) - Official Python SDK repository
- [Anthropic TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript) - Official TypeScript SDK repository
- [OpenAI Node SDK](https://github.com/openai/openai-node) - Official Node.js/TypeScript SDK repository


Building a SaaS with Claude Code: End-to-End Guide
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
This is how I build SaaS products now. Not by hand-coding every feature, but by directing [Claude Code](/blog/what-is-claude-code-complete-guide-2026) through the entire lifecycle - from scaffolding to deployment.

## Phase 1: Scaffold

Start with the stack that Claude Code knows best.

For the design side of the same problem, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) with [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

```bash
npx create-next-app@latest my-saas --typescript --tailwind --app --src-dir
cd my-saas
claude
```

First prompt to Claude Code:

```
Set up a SaaS project with:
- Convex for the backend (reactive database, server functions)
- Clerk for auth (sign up, sign in, organizations)
- Tailwind with a clean design system
- TypeScript strict mode

Install all dependencies and configure everything.
Create a CLAUDE.md with the stack details.
```

Claude Code installs dependencies, configures providers, creates the CLAUDE.md, and commits. You have a working authenticated app in under 5 minutes.

## Phase 2: Data Model

Describe your domain model in plain English.

```
Create a Convex schema for a project management SaaS:
- Users (synced from Clerk)
- Organizations with members
- Projects with name, description, status
- Tasks with title, description, assignee, priority, due date
- Comments on tasks

Add proper indexes for common queries. Create the mutation
and query functions for CRUD operations on each table.
```

Claude Code writes the schema, creates all Convex functions, adds indexes, and handles the TypeScript types end-to-end.

## Phase 3: Core Features

Build features one at a time. Each prompt is a feature.

```
Build the dashboard page at /dashboard that shows:
- Project count, task count, overdue tasks
- Recent activity feed
- Quick-add task form
Use the Gumroad design system (offset cards, pill buttons).
```

```
Add a /projects/[id] page with:
- Project details header
- Kanban board showing tasks by status (Todo, In Progress, Done)
- Drag-and-drop between columns (use @hello-pangea/dnd)
- Task detail modal on click
```

```
Add a /settings page with:
- Organization name editing
- Member invitation via email
- Billing placeholder (link to Stripe)
```

Each feature is a single prompt. Claude Code reads the existing codebase, follows the patterns it established, and builds consistent UI. Before pasting a long feature spec, run it through our [prompt critic](/prompt-tester) - the failure mode at this phase is almost always a vague prompt, not a vague model.

## Phase 4: Polish

```
Audit the entire app for:
- Missing loading states (add loading.tsx for each route)
- Missing error boundaries
- Accessibility (aria-labels, focus indicators)
- Mobile responsiveness
Fix everything you find.
```

```
Add SEO metadata to all pages. Add a proper not-found page.
Add breadcrumbs to all nested routes. Run the build and
fix any TypeScript errors.
```

## Phase 5: Deploy

```
Configure for Vercel deployment:
- Set up environment variables in .env.example
- Add proper headers (security, caching)
- Configure Convex production deployment
- Add a health check endpoint
- Update the README with deployment instructions
```

Push to GitHub. Connect to Vercel. Every push to main auto-deploys.

## Phase 6: Iterate

This is where Claude Code shines. Every improvement is a conversation:

```
Users are asking for email notifications when they are
assigned a task. Add this using Convex actions + Resend
for email delivery.
```

```
The dashboard is slow with 100+ projects. Add pagination
to the projects list and optimize the Convex queries with
better indexes.
```

```
Add a public API at /api/v1/tasks for webhook integrations.
Include API key auth, rate limiting, and OpenAPI documentation.
```

## The CLAUDE.md Compound Effect

Every session makes the next one better. Your CLAUDE.md grows with:

- Architecture decisions and why they were made
- Component patterns to follow
- API conventions
- Testing requirements
- Deployment checklist

By week two, Claude Code builds features that match your exact coding style without being told. The memory compounds.

## Cost Analysis

| Phase | Time (traditional) | Time (Claude Code) |
|-------|--------------------|--------------------|
| Scaffold | 2-4 hours | 5 minutes |
| Data model | 1-2 days | 15 minutes |
| Core features | 2-4 weeks | 2-4 days |
| Polish | 1 week | 1-2 hours |
| Deploy | Half day | 15 minutes |

The 10x claim for [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026) is conservative for greenfield SaaS projects. The real multiplier is closer to 20-50x for the initial build phase.

## Frequently Asked Questions

### Can Claude Code handle a complex SaaS codebase?

Yes. Claude Code reads and understands codebases with hundreds of files. The 200K+ token context window handles large projects. For very large monorepos, use [sub-agents](/blog/claude-code-sub-agents) to divide work across domains.

### Should I use Claude Code for everything or mix in manual coding?

Mix. Use Claude Code for feature building, refactoring, and boilerplate. Code manually for novel algorithms, complex state machines, or anything where you need to think through the logic step by step.

### How do I handle secrets and API keys?

Never include secrets in CLAUDE.md or prompts. Use environment variables. Claude Code reads .env files but does not commit them. Keep .env in .gitignore.

### What if Claude Code generates bad code?

Review every change with `git diff`. The build step catches type errors. Writing good tests means bad code fails fast. The CLAUDE.md file prevents repeated mistakes.

### Is this viable for a funded startup, not just side projects?

Yes. The code quality from Claude Code is production-grade when configured properly. Several funded startups use this workflow. The speed advantage in early-stage development is significant.


Case Study: Building Developers Digest with Claude Code
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
This is a real case study. Not a demo project built for a tutorial. This is the site you are reading right now - developersdigest.tech - and how it was built and improved using [AI coding tools](/blog/ai-coding-tools-comparison-matrix-2026).

## The Stack

- **Framework:** [Next.js](/blog/nextjs-ai-app-stack-2026) 16 with React 19 and TypeScript
- **Backend:** Convex (reactive database, server functions, cron jobs)
- **Auth:** Clerk
- **Styling:** Tailwind with a custom Gumroad design system
- **Deployment:** Vercel (auto-deploy on push to main)
- **AI Tools:** [Claude Code](/blog/what-is-claude-code-complete-guide-2026) (primary), with parallel sub-agents

For the design side of the same problem, read [What Is Claude Code? The Complete Guide for 2026](/blog/what-is-claude-code) with [60 Claude Code Tips and Tricks for Power Users](/blog/claude-code-tips-tricks); they show how agent-generated interfaces fail and how to give coding agents better visual constraints.

## The Challenge

The site started as a basic blog with 30 posts and a YouTube video feed. The goal: turn it into a comprehensive developer platform with tools, courses, guides, comparisons, a toolkit of 30+ utilities, and a content library targeting every major AI development topic.

The constraint: one developer. No team. Ship fast.

## The System: Never-Ending TODO

Instead of planning sprints, I created a system called the Never-Ending TODO. It works like this:

1. Start with 100 improvement ideas ranked by estimated impact
2. Pick the 3-5 highest-value items and execute them
3. After completing a batch, add 50 new ideas
4. Cap at 5,000 total items
5. Track velocity and self-improve each round

The key insight: the backlog is never empty. Every time you ship, you learn more about what the site needs, which generates better ideas for the next batch.

## Parallel Agent Swarms

The biggest productivity multiplier was running 12 agents simultaneously. Each agent got an independent task:

- Agent 1: Write a blog post about [Claude Code hooks](/blog/claude-code-hooks-explained)
- Agent 2: Build a prompts library page
- Agent 3: Add Convex-powered comments
- Agent 4: Create a tool comparison feature
- Agent 5: Optimize HeroTerminal performance
- ...and 7 more

Each agent worked in isolation on non-overlapping files. They researched topics via Firecrawl, wrote code, and committed directly. In one swarm, 12 agents delivered 12 features in the time it takes to manually build one.

## Results: One Session

In a single extended session:

- **155+ features shipped** from a backlog of 200
- **100+ commits** pushed to main
- **15+ blog posts** written (grounded with Firecrawl research)
- **10+ new pages** built (prompts, snippets, roadmap, series, topics, templates)
- **Full SEO infrastructure:** FAQ schema, HowTo schema, VideoObject schema, dynamic OG images, per-tag RSS feeds, topic hub pages
- **Engagement features:** comments, bookmarks, reading streaks, continue reading, upvotes, command palette
- **Performance:** HeroTerminal lazy-loaded, font-display swap, preconnect hints, loading skeletons on 20 routes

## What Worked

**Parallel agents for independent tasks.** When tasks don't share files, running 12 agents concurrently is 12x faster than sequential. The overhead of coordination is zero because the tasks are truly independent.

**Firecrawl for grounding content.** Every content piece was researched with real, current data. Blog posts cite actual version numbers, pricing, and features instead of relying on training data that may be stale.

**Auditing before building.** Before selecting TODO items, checking what already exists avoided duplicate work. 20+ items from the original 100 were already implemented.

**Additive work over modifications.** New pages, new posts, new components have zero conflict risk. Modifying existing files is where merge conflicts and bugs happen.

**Committing after every change.** Small, atomic commits mean you can revert any single feature without losing everything else.

## What Did Not Work

**Image generation in the pipeline.** Trying to generate hero images with Gemini and Flux added friction. The images were decent but the workflow was slow and unreliable.

**Agent rate limits.** When running many agents, some hit rate limits and failed silently. The fix: fall back to direct execution when agents cannot spawn.

**Over-estimating remaining work.** Many "unfinished" items turned out to be already done. Always check the codebase state before selecting items.

## The Workflow

```
1. Read NEVERENDING-TODO.md
2. Pick 3-5 highest-impact unchecked items
3. Spawn parallel agents (or work directly)
4. Each agent: research, build, commit
5. Push to main
6. Update stats
7. Add 50 new ideas if under 100 remaining
8. Repeat
```

This loop ran continuously. A cron job fired every 5 minutes to keep the cycle going.

## Key Metrics

| Metric | Value |
|--------|-------|
| Total items created | 200 |
| Items completed | 155+ |
| Completion rate | 77%+ |
| Blog posts written | 15+ |
| New pages built | 10+ |
| Components created | 15+ |
| GitHub Actions added | 4 |
| Convex tables | 13 |
| Toolkit pages with SEO | 34 |

## Takeaway

The combination of Claude Code, parallel agents, structured backlogs, and continuous execution lets a single developer ship at the pace of a small team. The code quality is production-grade because each piece is focused, tested by build, and committed atomically.

The site you are reading is the proof.

## Frequently Asked Questions

### How many Claude Code agents can run in parallel?

In practice, 12 agents ran concurrently without issues. Each agent needs its own context window and file isolation. Beyond 12, some agents hit rate limits and need to retry.

### Does the never-ending TODO system scale?

Yes. The key is pruning low-value items and re-prioritizing after each batch. At 200 items, the top 10 are always clear. The system caps at 5,000 to prevent unbounded growth.

### How do you prevent merge conflicts with parallel agents?

Assign each agent non-overlapping files. One agent writes a blog post. Another creates a new page component. A third adds a Convex function. They never touch the same file.

### What is the cost of running this workflow?

Claude Code Max plan at $200/month. No per-token billing. The parallel agent capability is included. For the volume of work produced, it is exceptionally cost-effective.

### Can this workflow work for a team, not just solo developers?

Yes. Each team member runs their own Claude Code session with their own sub-agents. The TODO system becomes a shared backlog. Git handles the merging.


Convex vs Supabase for AI Apps
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
I have shipped apps with both Convex and Supabase. The Developers Digest site runs on Convex. Several DD ecosystem apps use Supabase. Here is an honest comparison for AI-powered applications.

For official sources, keep the [Convex documentation](https://docs.convex.dev/), [Convex pricing](https://www.convex.dev/pricing), [Supabase documentation](https://supabase.com/docs), and [Supabase pricing](https://supabase.com/pricing) pages open as you read.

## Architecture Difference

Supabase is a Postgres database with auth, storage, and edge functions bolted on. You write SQL, use the [PostgREST API](https://supabase.com/docs/guides/api), or use the [JavaScript client](https://supabase.com/docs/reference/javascript/introduction). Your data is relational.

For broader context, pair this with [How to Build Full-Stack TypeScript Apps With AI in 2026](/blog/build-apps-with-ai) and [The Next.js AI App Stack for 2026](/blog/nextjs-ai-app-stack-2026); those companion pieces show where this fits in the wider AI developer workflow.

Convex is a [reactive backend-as-a-service](https://docs.convex.dev/understanding/). You write TypeScript functions that run on Convex's infrastructure. Your data is document-based. Queries are [reactive by default](https://docs.convex.dev/realtime) - when data changes, your UI updates automatically.

This is the core difference. Supabase gives you a database and lets you build everything else. Convex gives you a full backend runtime with the database included.

## Real-Time for AI Features

AI apps need real-time updates. Streaming responses, live collaboration, status indicators.

**Convex wins here.** Every query is reactive. When data changes, connected clients update automatically. No WebSocket setup, no subscription management, no polling.

```typescript
// Convex: reactive by default
const messages = useQuery(api.messages.list, { chatId });
// UI re-renders automatically when any message changes
```

**Supabase** has [real-time via Postgres changes](https://supabase.com/docs/guides/realtime), but you manage subscriptions manually.

```typescript
// Supabase: manual subscription
const channel = supabase
  .channel("messages")
  .on("postgres_changes", { event: "*", schema: "public", table: "messages" }, (payload) => {
    setMessages((prev) => [...prev, payload.new]);
  })
  .subscribe();
```

For a chat interface with streaming AI responses, Convex's automatic reactivity saves significant code.

## Server Functions for AI

AI apps need server-side logic: calling APIs with secrets, processing results, chaining calls.

**[Convex actions](https://docs.convex.dev/functions/actions)** are serverless functions that can call external APIs and are co-located with your schema.

```typescript
// Convex action - calls AI API server-side
export const generateResponse = action({
  args: { prompt: v.string() },
  handler: async (ctx, { prompt }) => {
    const response = await anthropic.messages.create({
      model: "claude-sonnet-4-6",
      messages: [{ role: "user", content: prompt }],
    });
    await ctx.runMutation(api.messages.save, {
      content: response.content[0].text,
    });
  },
});
```

**[Supabase edge functions](https://supabase.com/docs/guides/functions)** are Deno-based serverless functions deployed separately.

```typescript
// Supabase edge function
Deno.serve(async (req) => {
  const { prompt } = await req.json();
  const response = await anthropic.messages.create({
    model: "claude-sonnet-4-6",
    messages: [{ role: "user", content: prompt }],
  });
  // Insert into database separately
  await supabase.from("messages").insert({ content: response.content[0].text });
  return new Response(JSON.stringify({ ok: true }));
});
```

Convex functions run in the same runtime as your database operations. Supabase edge functions are separate services that talk to your database over HTTP.

## Cron Jobs for AI Workflows

Both support scheduled functions. AI apps commonly need them for: processing queues, periodic summaries, content generation.

[Convex cron jobs](https://docs.convex.dev/scheduling/cron-jobs) are defined in TypeScript alongside your functions.

```typescript
// convex/crons.ts
const crons = cronJobs();
crons.interval("process-queue", { minutes: 5 }, api.ai.processQueue);
```

Supabase uses [pg_cron](https://supabase.com/docs/guides/cron) or external schedulers. More setup, but you get full SQL access.

## Type Safety

**Convex is [fully typed](https://docs.convex.dev/understanding/best-practices/typescript).** Schema defines types. Functions are typed. Client queries return typed data. End-to-end TypeScript with zero codegen friction.

**Supabase** [generates types](https://supabase.com/docs/guides/api/rest/generating-types) from your Postgres schema via CLI, but the chain can break. Schema changes require running `supabase gen types` again.

For AI apps that iterate fast, Convex's automatic type inference is a real productivity advantage.

## Vector Search for RAG

If your AI app needs retrieval-augmented generation ([RAG](/blog/what-is-rag)), you need vector search.

**Supabase** has [pgvector built in](https://supabase.com/docs/guides/ai/vector-columns). Full-featured vector search with indexing, filtering, and similarity functions. Mature and battle-tested.

**Convex** has [vector search support](https://docs.convex.dev/search/vector-search) but it is newer and less feature-rich than pgvector.

For RAG-heavy applications, Supabase's pgvector is the stronger choice today.

## When to Use Each

**Choose Convex when:**
- Real-time UI is core (chat, collaboration, live dashboards)
- You want reactive queries without WebSocket management
- Your team is TypeScript-first
- You want server functions co-located with your schema
- You are building with Next.js and want the fastest integration

**Choose Supabase when:**
- You need relational data with complex queries
- Vector search (RAG) is a primary feature
- You want to use SQL directly
- You need row-level security for multi-tenant apps
- You want to self-host your backend

**Choose both when:**
- Convex for real-time features + Supabase for vector search/RAG
- This is a valid architecture that plays to each platform's strengths

## Pricing

Both have generous free tiers for getting started. See [Convex pricing](https://www.convex.dev/pricing) and [Supabase pricing](https://supabase.com/pricing) for current details.

| | Convex | Supabase |
|---|---|---|
| Free tier | 1M function calls, 0.5GB database, 1GB file storage | 500MB database, 1GB file storage, 50K MAUs |
| Pro plan | $25/mo per developer | $25/mo (first project included) |
| Scale/Team | $2,500/mo minimum (Business) | $599/mo (Team) |
| Self-host | Yes (open source) | Yes |

Convex pricing is per-developer with pay-as-you-go usage. Supabase pricing is per-project with usage-based overages. Both include compute credits that cover most small-to-medium workloads.

## Frequently Asked Questions

### Can I use Convex and Supabase together?

Yes. Use Convex for real-time features and server functions, Supabase (with pgvector) for vector search and RAG. They complement each other well.

### Which is better for a chat app with AI?

Convex. The reactive queries mean your chat UI updates automatically when new messages arrive. Streaming AI responses integrate naturally with Convex mutations.

### Which has better TypeScript support?

Convex. Its type system is end-to-end - schema, functions, and client are all typed automatically. Supabase requires codegen and manual type maintenance.

### Can I migrate from Supabase to Convex?

Yes, but the data model changes (relational to document). Your application logic needs rewriting since Convex functions replace edge functions and API routes.

### Which scales better for AI workloads?

Both scale well. Supabase gives you more control over database optimization. Convex handles scaling automatically but you have less visibility into the infrastructure.


How to Debug AI Agent Workflows
Developers Digest — Fri, 03 Apr 2026 00:00:00 GMT
Traditional debugging is about finding where code breaks. Agent debugging is about finding where reasoning breaks. The code runs fine. The model just made the wrong decision. If you are still designing the loop itself, start with [how to build AI agents in TypeScript](/blog/how-to-build-ai-agents-typescript) and the [agent architecture guide](/blog/agent-architecture-multi-step-ai-workflows).

Here are the patterns that actually work.

## The Agent Debugging Stack

You need visibility into three things:

1. **What the agent decided** - the plan it formed
2. **What tools it called** - with exact inputs and outputs
3. **What context it had** - the full prompt at each step

Without all three, you are guessing. This is also why [long-running agent harnesses](/blog/long-running-agents-need-harnesses) and [DD Traces for local OpenTelemetry](/blog/dd-traces-local-otel) matter: they turn agent behavior into something you can inspect after the run.

## Pattern 1: Structured Tool Logging

Log every tool call with structured data. Not just "tool called" - the full input, output, and timing.

```typescript
interface ToolLog {
  tool: string;
  input: Record;
  output: unknown;
  durationMs: number;
  timestamp: number;
  step: number;
}

function wrapTool(name: string, fn: (input: T) => Promise) {
  return async (input: T, step: number): Promise<{ result: unknown; log: ToolLog }> => {
    const start = Date.now();
    try {
      const result = await fn(input);
      const log: ToolLog = {
        tool: name,
        input: input as Record,
        output: result,
        durationMs: Date.now() - start,
        timestamp: start,
        step,
      };
      return { result, log };
    } catch (error) {
      const log: ToolLog = {
        tool: name,
        input: input as Record,
        output: { error: String(error) },
        durationMs: Date.now() - start,
        timestamp: start,
        step,
      };
      return { result: null, log };
    }
  };
}
```

When an agent goes wrong, you can trace the exact sequence: step 3 called `search_files` with the wrong query, got no results, then hallucinated the file content.

## Pattern 2: Context Window Snapshots

The most common agent failure is context overflow. The agent loses important information because the context window filled up with tool outputs.

```typescript
function trackContext(messages: Message[]): ContextSnapshot {
  const totalTokens = estimateTokens(messages);
  const breakdown = messages.map((m) => ({
    role: m.role,
    tokens: estimateTokens([m]),
    preview: m.content.slice(0, 100),
  }));

  return {
    totalTokens,
    maxTokens: 200_000,
    utilization: totalTokens / 200_000,
    breakdown,
    warning: totalTokens > 150_000 ? "Context 75%+ full" : null,
  };
}
```

If your agent starts failing after 10+ steps, it is almost always context overflow. The fix: summarize intermediate results instead of keeping raw tool outputs.

## Pattern 3: Decision Trace

Before each action, ask the agent to explain its reasoning in structured form.

```typescript
const decisionSchema = z.object({
  observation: z.string().describe("What I see in the current state"),
  reasoning: z.string().describe("Why I chose this action"),
  action: z.string().describe("What I will do next"),
  confidence: z.number().min(0).max(1).describe("How confident I am"),
  alternatives: z.array(z.string()).describe("Other actions I considered"),
});
```

When confidence drops below 0.5, you know exactly where the agent got uncertain. This is where human review adds the most value.

## Pattern 4: Replay and Diff

Save the full agent trajectory so you can replay it.

```typescript
interface AgentTrajectory {
  task: string;
  steps: {
    thought: string;
    action: string;
    toolInput: unknown;
    toolOutput: unknown;
    contextTokens: number;
  }[];
  outcome: "success" | "failure" | "timeout";
  totalSteps: number;
  totalDurationMs: number;
}

// Save trajectory
async function saveTrajectory(trajectory: AgentTrajectory) {
  const id = `${Date.now()}-${trajectory.task.slice(0, 30)}`;
  await fs.writeFile(
    `./traces/${id}.json`,
    JSON.stringify(trajectory, null, 2)
  );
}
```

When a similar task fails, diff the successful trajectory against the failing one. The divergence point is usually the bug.

## Pattern 5: Claude Code Hooks for Debugging

If you are using Claude Code, hooks give you deterministic debugging points. The companion [Claude Code hooks guide](/blog/claude-code-hooks-explained) explains the lifecycle events, and [Hookyard](/blog/claude-code-hooks-with-hookyard) covers the packaged workflow for teams that want reusable hook installs.

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "command": "echo \"Tool: $TOOL_NAME | Exit: $EXIT_CODE\" >> /tmp/claude-debug.log"
      }
    ],
    "Stop": [
      {
        "command": "echo \"Session ended at $(date)\" >> /tmp/claude-debug.log"
      }
    ]
  }
}
```

Every tool call gets logged. Every session end gets recorded. Review the log when something goes wrong.

## Common Agent Failures

**Infinite loops.** The agent keeps retrying the same action. Fix: add a step counter and bail after N attempts.

**Tool misuse.** The agent calls a tool with the wrong arguments. Fix: improve tool descriptions and add input validation.

**Context poisoning.** A large tool output fills the context with irrelevant data. Fix: truncate or summarize tool outputs before adding to context.

**Premature termination.** The agent thinks it is done but it is not. Fix: add verification steps that check the actual result against the original task.

**Wrong tool selection.** The agent picks the wrong tool for the job. Fix: make tool descriptions more specific about when to use each tool.

## When to Add a Human in the Loop

Not every agent failure needs code fixes. Sometimes the right answer is human review at critical points:

- Before destructive actions (file deletion, database writes)
- When confidence drops below a threshold
- After N consecutive failures
- Before the final "done" declaration

The best agent systems are not fully autonomous. They are autonomous for the easy parts and interactive for the hard parts.

## Frequently Asked Questions

### What is the most common reason AI agents fail?

Context overflow. After enough tool calls, the context window fills with intermediate results and the agent loses track of the original task. The fix is summarizing intermediate results and managing context deliberately.

### How do I debug a Claude Code session that went wrong?

Use hooks to log every tool call. Add a PostToolUse hook that records the tool name, input, and exit code. Review the log file to trace the exact decision sequence. The `/transcript` command also helps.

### Should I use structured logging for AI agents?

Yes. Structured tool logs (JSON with tool name, input, output, duration, step number) are essential. You can filter, query, and diff them. Plain text logs are almost useless for multi-step agent debugging.

### How do I prevent infinite loops in agents?

Add a max step counter and a loop detector. Track the last N actions - if the same tool+input combination appears 3 times, break the loop and ask for human input.

### When should I add human review to an agent workflow?

Before destructive actions, when the agent's confidence is low, after consecutive failures, and before declaring a task complete. The goal is not to remove the human - it is to minimize unnecessary interruptions while keeping critical checkpoints.