标签：#code

A deep dive into the 3-way battle for the developer's desktop—comparing AI depth, flow state, autonomous agents, and real-world productivity. Three years ago, choosing a code editor was simple: you downloaded VS Code, installed your favorite syntax theme, added a few extensions, and got to work. Today, developer tooling has undergone a seismic shift. AI isn't just an extension sitting in a sidebar; it's driving entire workflows, editing dozens of files simultaneously, and executing complex engineering tasks. Enter the primary contenders dominating the developer landscape: VS Code (+ GitHub Copilot): The battle-tested industry titan with unmatched ecosystem depth. Cursor: The pioneer of the AI-native fork, built specifically for flow state and multi-file orchestration. Windsurf: Codeium's AI-first editor featuring autonomous flow state agents and deep context tracking. If you're trying to figure out which editor will give you or your engineering team the highest return on productivity, here is a practical, data-informed breakdown. The Architectural Divide: Plugins vs. AI-Native Forks Before comparing feature lists, it helps to understand the underlying architecture: VS Code remains an extension-first model. The core editor is unchanged, while GitHub Copilot operates alongside it as an assistant. Cursor and Windsurf are VS Code forks. Their creators modified the editor at an architectural level to give the AI direct access to your local workspace, terminal, file system, and git context. This distinction dictates how each editor feels when you're in the middle of a complex coding session. 1. Inline Autocomplete & Flow State When writing code line-by-line, friction is the enemy of productivity. Cursor Famous for its ultra-fast multi-line predictions. Cursor predicts not just the next token, but your next probable edit location across nearby lines. It keeps you in a continuous "flow state" where hitting Tab feels almost telepathic. Windsurf Features "Supercomplete" inlin

Bilibili's 412 Incident, Explained: How v1.5.0 Absorbed It In June 2026, Bilibili quietly began rejecting yt-dlp with HTTP 412 errors. Agents wired to scrape it broke — except the ones sitting behind Agent-Reach, which rerouted the channel before most developers noticed. Agent-Reach is a local, MIT-licensed capability layer that gives shell-capable coding agents live internet access by selecting and routing to upstream CLIs rather than proxying data itself . When Bilibili started 412-blocking yt-dlp in June 2026, v1.5.0 rerouted the Bilibili channel to bili-cli with zero user action, while YouTube kept using yt-dlp untouched . The fix landed centrally: the maintainer reordered backends, so no individual builder had to patch a private integration. Quick Answer: When Bilibili began returning HTTP 412 to yt-dlp in June 2026, Agent-Reach v1.5.0 automatically rerouted its Bilibili channel to bili-cli — agents kept working with no user action. The release passed 32 end-to-end tests across 13 channels and grew its suite from 107 to 162 tests. The framing shift matters: v1.5.0 describes itself as a capability layer, not a tool collection. Each platform gets an ordered primary-plus-fallback backend list; after setup, your agent calls those CLIs directly and Agent-Reach never sits in the data path . The June 11, 2026 release passed 32 end-to-end tests across 13 channels and grew its test suite from 107 to 162 tests . Platform Primary backend Fallback Web pages Jina Reader — YouTube yt-dlp — GitHub gh CLI — RSS feedparser — Bilibili bili-cli OpenCLI (subtitles) Twitter/X twitter-cli OpenCLI Reddit OpenCLI rdt-cli XiaoHongShu OpenCLI xhs-cli LinkedIn linkedin-mcp Jina Reader Global search Exa via mcporter — "capability layer: multi-backend routing + real doctor + OpenCLI" — Agent-Reach v1.5.0 release framing (source: Agent-Reach CLAUDE.md ). The behavior is easy to model. The following minimal snippet — which was executed and returns exit 0 — illustrates the "absorb and keep wo

📝 Originally published (in Japanese) at forge.workstyle.tech . You've got a code that looks correct when read, but when you open it in the browser, it's slightly different from the mockup - this "visual discrepancy" is the most troublesome part of UI development. A slight CSS specification, nesting of elements, and flex wrapping. Discrepancies that cannot be noticed by statically reading the code together will only appear when actually rendered. Until now, it was necessary for a human to open the screen in a browser, compare it with the mockup image, and verbally communicate the differences to the AI. This workflow replaces the process of "humans visually seeing and verbalizing" by showing the screen to the AI agent itself via the browser . By combining Claude Code and browser automation extensions (Chrome extensions), we will "see" the screen actually rendered on localhost, compare it with the mockup, identify layout discrepancies, and fix them. Why is it necessary to "show the actual screen"? There are limitations to just handing over the code for UI review. It's difficult for both humans and AI to completely reproduce the final rendering result in their minds from the code. In particular, these discrepancies are difficult to detect just by looking at the code. Layout skeleton discrepancies - One area is crushed when it's supposed to be a 2-column layout, or the vertical split ratio is different from the mockup, resulting in structural-level discrepancies Element placement errors - A preview that should be in the upper right column is wrapped around to the bottom Unexpected wrapping and overflow - The component wraps due to insufficient width, changing the impression from the mockup These discrepancies cannot be determined without seeing the "rendering result" as a fact. That's why we show the actual screen to the AI. Workflow: Show, Compare, and Fix 1. Provide the mockup as a baseline First, provide the target mockup image to the AI and share the baseline that "t

Industrializing the disassembly of an undocumented processor from a raw binary is a complex task that can be broken down into four key steps: Verify that the binary does not belong to a known processor. Verify that the binary is not obfuscated, compressed, or encrypted code for a known processor. Build an undocumented processor generator. Create the analysis pipeline and custom disassembler generation process. For the first phase of this project, the goal is to build dedicated, lightweight disassemblers—since, for bare-metal binaries, tools like Ghidra require manual processor target selection before analysis can begin. 1. Why Build a Custom Disassembler? To determine whether a binary was compiled for a specific architecture, the strategy consists of disassembling the binary (both statically and dynamically) against candidate instruction sets until: One or more bytes fail to match any valid instruction for that architecture, allowing us to rule it out. The disassembly succeeds completely. (Note: a successful disassembly does not guarantee that the binary was originally intended for that CPU; control flow validity must also be verified). Static disassembly is the first line of defense. However, if it fails due to obfuscation, compression, or encryption, we must escalate to dynamic execution and analysis. Only after systematically eliminating all known architectures can we confidently conclude that we are dealing with a custom or undocumented processor . 2. How to Build Your Custom Disassembler Before deploying heavy machinery for undocumented processors, the logical first step was to check against known architectures. Approach 1: Ghidra and SLAgh Ghidra relies on the SLAgh specification language and maintains an extensive library of processor definitions. The original plan was to leverage its API to extract a normalized opcode mapping table. However, after several attempts, Ghidra proved unsuitable for this specific pipeline for two reasons: Operand Type Loss: Detail

Today, I’m talking with Toni Schneider, who is the brand new CEO of the social platform Bluesky — he formally took over after a short stint as interim CEO. This is one of my favorite kinds of interviews to do on Decoder, because a couple years ago, we had Bluesky’s prior CEO, Jay Graber, on […]

Hello Devs 👋 AI coding assistants have dramatically accelerated code generation. Whether you're using Cursor, GitHub Copilot, Claude Code, or Windsurf, writing code is faster than ever. The challenge is that code review hasn't improved at the same pace. Teams are shipping larger pull requests, reviewing more AI-generated code, and spending increasing amounts of time validating whether changes are actually correct, maintainable, and aligned with existing architecture. That's exactly why AI code review tools have become a key part of modern GitHub workflows. The problem is that not all AI review tools solve the same problem. Some generate pull request summaries. Some focus on security and compliance. Some extend traditional static analysis. Others attempt to understand repository-wide context and review changes the way an experienced teammate would. If you're evaluating AI code review tools for GitHub, here's a practical comparison of the most widely discussed options in 2026. ⚡ Quick Verdict Qodo stands out for teams that need automated pull request reviews with repository-wide context, not just diff analysis. The GitHub integration is straightforward, reviews run automatically on pull requests, and the platform focuses on understanding dependencies, related files, and existing code patterns across the repository. For small projects, lightweight review tools may be sufficient. For larger codebases, AI-generated code, and complex pull requests, context-aware review becomes significantly more valuable. What Makes a Good GitHub AI Review Tool? Before comparing tools, it's worth defining what actually matters. For most engineering teams, four factors determine whether an AI review tool provides real value. 1. Integration Reviews should appear where developers already work, directly inside GitHub pull requests. Nobody wants another dashboard, notification stream, or workflow to manage. 2. Review Quality Useful reviews surface meaningful issues, not just more comments. The

The problem is not the code I build Flutter apps. A normal feature touches four layers at once. Models and json parsing Repository and API client State management Screens and widgets When I ship that as one branch, the pull request is somewhere between 1,000 and 4,000 lines. And then one of two things happens. Either the reviewer opens 40 files, scrolls for ten minutes, and writes "looks good". That is not a review. That is a signature. Or the reviewer does the job properly, takes three days, and leaves a comment on the models file. Now every screen above it has to change. The writing was fast. The review was slow. That is the real bottleneck. The old workaround You already know it. Split the work into branches yourself. git checkout -b feat/booking-models git checkout -b feat/booking-repo # branched off models git checkout -b feat/booking-state # branched off repo git checkout -b feat/booking-ui # branched off state This works for about one day. Then a reviewer asks for a change in feat/booking-models , and you rebase three branches by hand. Then it happens again. Most people give up and go back to the giant branch. What stacked pull requests change On July 30 2026 GitHub put stacked pull requests into public preview. The idea is small. A stack is an ordered series of pull requests. Each pull request targets the one below it instead of targeting main . Only the bottom one targets main . PR #4 screens and widgets -> targets PR #3 PR #3 cubits and state -> targets PR #2 PR #2 repository and api -> targets PR #1 PR #1 models and parsing -> targets main Because each pull request only contains its own layer, opening PR #3 shows you the state management diff and nothing else. Not the models. Not the widgets. The Flutter example Say I am building a booking flow. Here is the same feature, sliced. PR 1 - models and json parsing. Around 190 lines. Targets main. class Booking { final String id ; final DateTime startsAt ; final BookingStatus status ; const Booking ({ required

Originally published on tamiz.pro . The initial euphoria surrounding Large Language Models (LLMs) was largely driven by their ability to generate code. We saw demos of developers asking an LLM to write a React component, a Python data pipeline, or a SQL query, and watching it appear instantly. This capability, while impressive, is fundamentally different from the engineering challenges posed by AI Agents. A code generator is a stateless tool; an AI Agent is a stateful, autonomous entity that interacts with external systems, makes decisions, and executes actions over time. Treating an AI Agent like a code generator is the primary reason most AI projects fail to reach production. When you move from generating static artifacts to orchestrating dynamic, multi-step workflows, the complexity shifts from syntax correctness to systemic reliability. In this deep dive, we explore why production-grade AI Agents require a paradigm shift in engineering, focusing on three critical pillars: rigorous state management, comprehensive observability, and deterministic control flows. The Fundamental Shift: Stateless Generation vs. Stateful Execution To understand the engineering gap, we must first distinguish between what a code generator does and what an agent does. A Code Generator operates in a Request -> Response loop. The input is a prompt; the output is a snippet of code. The LLM does not retain memory between calls, does not modify external state (like a database), and does not decide its own next steps based on runtime errors. It is a function with high entropy. An AI Agent is a loop. It observes the environment, reasons about the next best action, executes that action (often via tools or APIs), and observes the result. This creates a feedback loop: Observe -> Think -> Act -> Observe -> Think -> ... This loop introduces several engineering complexities that static code generation does not: Non-Determinism: The agent’s path through the workflow is not fixed. It depends on the LLM

The Core Argument : AI agent reliability isn't achieved by "making the agent smarter" — it's achieved by the simple engineering principle of separating validation from generation . Quality isn't accidental. It's designed. What You'll Learn : Maker/Checker separation, 6 termination conditions, and an automated feedback loop — all with runnable code. 0. Prerequisites Python ≥ 3.10 OpenAI API Key (or compatible interface) pip install openai>=1.0.0 (Optional) pip install anthropic>=0.30.0 if using Claude as Checker 1. The Pain: Why "Agent Checks Itself" Is a Trap 1.1 The Copying of Cognitive Bias A team built a data-analysis agent. It pulled sales data from a database and generated business reports. The team added a "self-review" step: after generating, the agent told itself "please check if the data you just output is accurate." Result? The agent always replied "data is accurate." Even when the team deliberately injected obvious errors (e.g., monthly sales of -50M RMB), the agent confidently said everything was fine. This isn't the model being "disobedient." It's a more fundamental issue: when the generator and checker are the same entity, the check is just a restatement of the generation process — not real validation. The checker carries the exact same cognitive bias, knowledge boundaries, and reasoning path as the generator. 1.2 The Amplifier Effect of Confirmation Bias Self-checking also triggers a subtler problem: confirmation bias amplification. The model builds a "belief state" during generation; when re-examining, it tends to confirm rather than overturn. Experiment data (from Anthropic research): Same model does "generate → self-review": ~12% error-correction rate A separate model instance reviews: ~37% error-correction rate A different model family reviews: ~52% error-correction rate 1.3 The Value of Independence First principle of quality assurance: the checker must be independent of the generator. In agent architecture, the engineering expression of this is

HashiCorp has introduced tfpolicy, a new HCL-based policy-as-code framework for Terraform, now available in public beta within HCP Terraform. It is designed to simplify and modernize infrastructure governance by integrating policy creation and enforcement directly into Terraform workflows, eliminating the need for separate tools and languages. By Sergio De Simone

How a branch-free loop and byte-space arithmetic let GitHub case-fold every byte of code search at >45 GiB/s on a single core. The post Don’t stop early: Case-folding source code at memory speed appeared first on The GitHub Blog .

Dropbox has integrated Model Context Protocol (MCP) with its internal knowledge platform, Dash, to surface security design context during AI assisted code reviews. The system retrieves threat models and security requirements for pull requests, helping reviewers validate implementation against design intent. An InfoQ Q&A explores the architecture and key lessons learned. By Leela Kumili

code-server is the open-source project that runs full VS Code including extensions, integrated terminal, Git, IntelliSense — on a remote server, accessible from any browser. This guide deploys it on Ubuntu 24.04 with Docker Compose, fronted by Traefik for automatic HTTPS. Prerequisites: an Ubuntu 24.04 server (1GB RAM / 2 vCPU minimum), a domain A record (e.g. code.example.com ), Docker and Docker Compose installed. Set Up the Project $ mkdir -p ~/vscode-server/ { project,config,local,letsencrypt } $ cd ~/vscode-server project — your editable workspace config — code-server settings/extensions local — user-specific data letsencrypt — Traefik's ACME certificate storage Find your UID/GID and add yourself to the docker group: $ id $USER $ sudo usermod -aG docker $USER Write the Compose File $ nano docker-compose.yml services : code-server : image : codercom/code-server:latest container_name : code-server user : " UID:GID" # Replace with your user's UID and GID environment : - PASSWORD=SECURE_PASSWORD # Replace with a strong password - DOCKER_USER=LINUXUSER # Replace with your username volumes : - ./project:/home/coder/project - ./config:/home/coder/.config - ./local:/home/coder/.local networks : - internal restart : unless-stopped labels : - " traefik.enable=true" - " traefik.http.routers.code-server.rule=Host(`CODE.EXAMPLE.COM`)" # Replace with your domain name - " traefik.http.routers.code-server.entrypoints=websecure" - " traefik.http.routers.code-server.tls.certresolver=myresolver" - " traefik.http.services.code-server.loadbalancer.server.port=8080" traefik : image : traefik:latest container_name : traefik ports : - " 80:80" - " 443:443" volumes : - /var/run/docker.sock:/var/run/docker.sock:ro - ./letsencrypt:/letsencrypt command : - " --providers.docker=true" - " --providers.docker.exposedbydefault=false" - " --providers.docker.network=internal" - " --entrypoints.web.address=:80" - " --entrypoints.websecure.address=:443" - " --entrypoints.web.http.redirections.entr

1. Introduction and Problem Statement In constrained embedded systems engineering, 8051-type microcontrollers remain ubiquitous. Often coupled with external or internal EEPROM memories of very limited size (a few kilobytes), these environments leave no room for excess. Using high-level compilers like SDCC, while convenient for rapid prototyping, generates heavy code (function prologues, complex stack management) that becomes prohibitive when attempting to insert surgical modifications into an existing binary. This article details the methodology of intercepting an SDCC-compiled function via a direct binary hook (jump) and redirecting execution flow to an optimized pure assembly routine located in an unused memory area (slack space), with the goal of conditionally bypassing a critical logic test when a specific trigger condition is met 2. 8051 Architectural Constraints and Low-Level Logic The 8051 instruction set is rudimentary yet extremely direct. Every recovered byte of memory space represents an insertion opportunity for a control payload. By replacing compiler-generated structures with direct assembly sequences, space waste is eliminated and register cycles are precisely controlled. Tactical Objective: Modify the behavior of a validation function (e.g., a security or integrity test) so that it systematically returns a negative response (False / 0x00) under the effect of a stealthy trigger, while maintaining 100% transparent nominal behavior the rest of the time. 3. Designing the Pure Assembly Patch Imagine an original routine performing a classic conditional check. The original code evaluates a state and jumps depending on the result. #include <mcs51/8051.h> // Simulated security check function generated by SDCC unsigned char verify_system_integrity ( void ) { unsigned char status = 0 ; // Read a configuration or state register status = P1 ; // Critical security test if ( status == 0x5A ) { return 0x01 ; // Success / Authorized } return 0x00 ; // Failure / Unaut

Introduction to Clean Architecture Clean architecture, a software design philosophy championed by the renowned Robert C. Martin (Uncle Bob), has revolutionized the way developers approach system design. By prioritizing the separation of concerns and promoting independence From frameworks, user interfaces, and databases, clean architecture empowers developers to build robust, maintainable, and scalable systems. This design approach is not just a theoretical concept, but a practical solution for real-world problems. In this guide, we'll explore the principles of clean architecture and provide a step-by-step roadmap for implementing it in your own projects, so you can get started with clean architecture and Unlock its full potential. Independent of Frameworks: Your business logic shouldn't depend on external libraries Testable: Business rules can be tested without UI, database, or external services Independent of UI: You can swap web UI for console UI without changing business logic Independent of Database: You can swap SQL Server for MongoDB without changing business rules Independent of External Services: Business rules don't know about external services Core Principles Clean Architecture organizes code into concentric circles, with dependencies pointing inward: 1. Entities (Inner Circle) These are the business objects of your application. They contain enterprise-wide business rules and are the most stable part of your system. public class User { public string Id { get ; set ; } public string Email { get ; set ; } public string Name { get ; set ; } public bool IsValid () { return ! string . IsNullOrEmpty ( Email ) && Email . Contains ( "@" ); } } 2. Use Cases (Application Layer) This layer contains application-specific business rules. It orchestrates the flow of data to and From entities. public class CreateUserUseCase { private readonly IUserRepository _repository ; public async Task < User > Execute ( CreateUserRequest request ) { var user = new User { Email = requ

tinyNpm is a vs code extension that helps protect you from supply chain attacks, stale packages, and bloated code! I had been using package.json version keepers for quite some time but after the big supply chain attack i thought they would be the perfect place to add in some security. The idea is just to provide the latest package number x days old. This will help prevent most of the danger in supply in chain attacks. It will also remove the ^ if you have it so you can better control what version of a package your application is using. To be more security focused it gives general hints in the hover menu to help keep an eye on the packages you have installed. These hints include warnings for staleness, high dependency count, and number of downloads. Since all of this is something you can get through the npm api, I called it tinyNpm You can download it on the marketplace

Every idea gets run through a one-sentence test before it is allowed to count as a real idea at all Most ideas die for one of three specific reasons, not vague lack of enthusiasm An idea only earns a build slot once it has survived contact with a real, repeated problem A maybe-later list holds the rest on purpose, and I check it far less often than people assume The One-Sentence Test I Run Before Anything Becomes an Idea I get more ideas than I could ever build. That is not a boast, it is a liability if I do not manage it, because every one of those ideas feels exciting for about twenty minutes, and excitement is a terrible filter for what is actually worth my evenings. So before an idea is allowed to sit on any kind of list, it has to pass one test: can I describe the smallest useful version of it in a single sentence, with no "and" in the middle. That sounds small, but it kills more ideas than any other step in the process. "A tool that tracks my Claude usage and also shows analytics and also has a community feature" does not pass. "A tool that warns me before I hit my usage limit" passes. The first sentence is a pitch for a platform. The second sentence is a pitch for a Tuesday evening. I want the second kind, because the second kind is the one I actually finish. I did not always work this way. Early on, an idea earned space on my list the moment it sounded interesting, and my list grew into a graveyard of half-described plans that all needed a paragraph to explain. A paragraph is a warning sign now, not a feature. If I need more than one sentence to say what the smallest version does, the idea has not actually taken shape yet, it has just acquired enthusiasm, and those are different things. The test also forces honesty about scope early, before I have sunk any real time into something. An idea that needs "and" is usually two or three ideas wearing a trenchcoat, and pulling them apart at the sentence stage is far cheaper than pulling them apart three weeks into a

Bridging the Gap: Navigating the Chasm Between Academic Coding and Real-World Software Development The transition from academic coding to professional software development is fraught with challenges, particularly when it comes to navigating and debugging large, unfamiliar codebases. This gap, often overlooked in educational curricula, leaves new developers ill-prepared for the complexities of real-world projects. Below, we dissect the technical mechanisms involved in codebase navigation and debugging, their constraints, and the resulting instabilities, while reflecting on the disconnect between academic training and industry expectations. Mechanisms of Codebase Navigation and Debugging The process of understanding and working within a large codebase involves several interconnected mechanisms. Each plays a critical role in a developer's ability to efficiently and accurately contribute to a project. Code Navigation : Involves traversing a codebase using tools like "go to definition" to map code structure and dependencies. This mechanism relies on the developer's ability to interpret relationships between files and functions. Impact : Efficient navigation reduces time spent understanding the codebase. Internal Process : Iterative exploration of code paths. Observable Effect : Reduced time to locate relevant code segments. Code Comprehension : Analyzing existing code to infer purpose, logic, and side effects. Requires pattern recognition and logical deduction. Impact : Accurate comprehension minimizes unintended modifications. Internal Process : Mental modeling of code behavior. Observable Effect : Correct identification of code functionality. Debugging : Identifying and resolving bugs while minimizing collateral damage. Relies on isolating root causes and understanding dependencies. Impact : Effective debugging prevents regressions. Internal Process : Hypothesis testing and validation. Observable Effect : Bug resolution without introducing new issues. Documentation Ana

Any application that ships across borders needs a way to name a country. You reach for a two-letter code, write US , JP , DE , and move on. Then a support ticket arrives. A user in Belfast picked "United Kingdom" and your shipping API rejected UK . Someone in Pristina found no option at all. Your analytics dashboard shows a country called AN that dissolved in 2010. These bugs share one root: ISO 3166-1 alpha-2 carries more rules than its two characters suggest. Let's walk through the parts that break real applications, and how to model country data so the next revision of the standard does not break yours. Key takeaways ISO 3166-1 defines 249 officially assigned alpha-2 codes. UK is not one of them. The United Kingdom is GB . Four other status categories exist: user-assigned, exceptionally reserved, transitionally reserved, and indeterminately reserved. They follow different rules. Kosovo uses XK , a code from the user-assigned range that ISO has never officially assigned. Codes get recycled. CS meant Czechoslovakia, then Serbia and Montenegro. Country names change far more often than their codes. Store the code, resolve the name at render time. What alpha-2 covers ISO 3166 splits into three parts. Part 1 names countries and their dependent territories. Part 2 names subdivisions inside them. Part 3 records codes that fell out of use. Part 1 gives you three code sets for the same entity: Format Japan Notes Alpha-2 JP Two letters. Used by ccTLDs, BCP 47 language tags, payment APIs. Alpha-3 JPN Three letters. Easier to read on its own. Numeric-3 392 Digits from UN M49. Script-independent, survives alphabet changes. Alpha-2 is the set you meet most often. Two characters fit anywhere, and the Internet Assigned Numbers Authority (IANA) draws the country-code top-level domains straight from the alpha-2 list, which puts these codes in front of everyone who ever registered a domain. That reach explains the misuse. Five kinds of code The 249 official codes get the attention.

This is a continuation of my "Claude Code environment" series. In the previous post, Automatically thinning conversation logs to prevent bloat , I introduced the basic pattern for scheduled launchd jobs. This time I'm using that same mechanism to automatically maintain a list of the custom agents in ~/.claude/agents/ . Dropping a single .md file into ~/.claude/agents/ adds a custom agent, but before long you lose track of how many you have, what model each one uses, and which tools each is allowed to touch. That's exactly what happened to me with the 27 agents I now have. I tried writing an INDEX.md by hand to manage them, and of course within a few days it had drifted from reality. The problem: the index rots Manually updating INDEX.md every time you add a custom agent is not sustainable. You forget you added one and leave it out You change a model later and never reflect it in INDEX.md You typo a name or description and never notice I concluded there was no sustainable way to manage this other than "generate it automatically," so I wrote agents-index.sh . The output: a real INDEX.md Here's how the top of my current ~/.claude/agents/INDEX.md looks. <!-- AUTO-GENERATED by ~/.claude/scripts/agents-index.sh — DO NOT EDIT MANUALLY --> # Agents Index (27 agents · 2026-07-28 02:02) | Name | Model | Description | Tools | |------|-------|-------------|-------| | `architect` ( [ architect.md ]( ./architect.md ) ) | opus | Software architecture specialist ... | ["Read", "Grep", "Glob"] | | `build-error-resolver` ( [ build-error-resolver.md ]( ./build-error-resolver.md ) ) | sonnet | Build and TypeScript error resolution specialist ... | ["Read", "Write", "Edit", "Bash", "Grep", "Glob"] | | `doc-updater` ( [ doc-updater.md ]( ./doc-updater.md ) ) | haiku | Documentation and codemap specialist ... | ["Read", "Edit", "Bash", "Grep", "Glob"] | Four columns: Name, Model, Description, and Tools. You can see at a glance how the models break down across opus / sonnet / haiku , and i