{"version":"https://jsonfeed.org/version/1","title":"Human Who Codes","home_page_url":"https://humanwhocodes.com","feed_url":"https://humanwhocodes.com/feeds/all.json","description":"The Official Web Site of Nicholas C. Zakas","expired":false,"author":{"name":"Nicholas C. Zakas"},"items":[{"id":"https://humanwhocodes.com/blog/2026/04/improving-developer-velocity-github-merge-queue/","url":"https://humanwhocodes.com/blog/2026/04/improving-developer-velocity-github-merge-queue/","title":"Improving developer velocity with GitHub merge queue","author":{"name":"Nicholas C. Zakas"},"summary":"GitHub merge queue reduces the manual churn of keeping pull requests current by automatically retesting them in order before merge.","content_text":"\nImagine this: you're working at a company that uses GitHub as its source control platform. Each repository follows established best practices, such as requiring continuous integration (CI) tests to pass before a pull request can be merged. Branch protection rules maintain a linear commit history and require pull requests to be approved before merging. Developers may merge their own pull requests once CI passes and they have the required approvals.\n\nThe linear commit history requirement means that each pull request must be tested on top of `HEAD` in CI before it can be merged. GitHub provides an \"Update Branch\" button on pull requests for this purpose. As a developer, you click \"Update Branch\" and wait for CI to pass again.\n\nUnfortunately, CI takes ten minutes to run, so you step away for a bathroom break and a snack. When you get back to your desk, CI has passed, but the \"Update Branch\" button is enabled again. In the time it took CI to finish, someone else merged a pull request, so you have to start the entire process over.\n\nThe situation is frustrating with just one pull request, so imagine what happens if you and other engineers often have more than one open at a time. That means jumping back and forth between pull requests, repeatedly clicking \"Update Branch,\" and waiting to see whether this is the time you actually make it through before someone else merges a different pull request.\n\nIn situations like this, the GitHub merge queue can free up developer time by eliminating the babysitting of pull requests.\n\n## What does a GitHub merge queue do?\n\nA GitHub merge queue acts as an intermediate step between approving a pull request and landing its commit on the target branch. Instead of merging a pull request as soon as it's ready, you add it to the merge queue. The queue collects pending pull requests and tests each one on top of the others, up to a maximum batch size of five by default. You can configure the same CI tests to run for the merge queue, and pull requests are kicked back to their authors if those tests fail.\n\nBehind the scenes, GitHub waits until the maximum batch size is available, unless a configurable timeout is reached, and then adds the pull requests to a temporary branch based on `HEAD` in queue order. CI runs for each pull request as it is added to the temporary branch, and the next pull request is added only after the previous one's CI checks pass. If a pull request fails CI, it is removed from the queue for further review by the author. The original pull request remains open on GitHub until it is successfully merged through the merge queue. The temporary branch containing the previously passing pull requests is merged into `HEAD`, and a new temporary branch starts with the pull request immediately after the failing one. The process then continues.\n\nOnce GitHub has a temporary branch where all pull requests have passed CI, it merges those commits into `HEAD` in a single operation. The commits land in the same order they appeared in the merge queue.\n\nThe biggest advantage of this approach is that every pull request is automatically tested on top of all the pull requests that came before it in the queue. You never have to click \"Update Branch\" because that effectively happens as part of the merge queue process. CI now runs twice: once before the pull request is added to the queue and again during temporary branch creation. That dramatically reduces the manual work required to land a pull request on `HEAD`.\n\nAnother advantage is that the merge queue is editable. You can reorder pull requests or remove them from the queue before they are merged, giving you full control over which pull requests move forward and which ones wait.\n\n## Setting up a GitHub merge queue\n\nTo set up a merge queue for a repository, there are three steps:\n\n1. Ensure your CI tests run in the merge queue\n2. Enable squash merges for the repository\n3. Enable the merge queue with a ruleset\n\nEach step is important for the overall operation of the merge queue.\n\n### Ensure your CI tests run in the merge queue\n\nThe first step in setting up a GitHub merge queue is configuring CI for the queue. You can do that by adding the `merge_group` trigger[^merge-group-trigger] to the same GitHub workflow file that runs CI for pull requests:\n\n```yaml\non:\n pull_request:\n branches: [main]\n merge_group:\n branches: [main]\n types: [checks_requested]\n```\n\nThis ensures you're running the same checks when a pull request is opened or updated and when a merge queue group is tested. As of this writing, `checks_requested` is the only available `merge_group` type.\n\nYou should also review the jobs in your CI workflow to make sure they all make sense to run on the merge queue branch. The merge queue CI process won't have access to pull request-specific information, such as the pull request title or pull request branch name. You can scope jobs to not run for the merge queue using an `if` condition, like this:\n\n```yaml\njobs:\n lint:\n if: github.event_name != 'merge_group'\n runs-on: ubuntu-latest\n steps:\n - run: echo \"linting...\"\n```\n\nAlternately, you can check the current branch name to see if it's a merge queue branch, which exists under `refs/head/gh-readonly-queue/`:\n\n```yaml\njobs:\n lint:\n if: ${{ !startsWith(github.ref, 'refs/heads/gh-readonly-queue/') }}\n runs-on: ubuntu-latest\n steps:\n - run: echo \"linting...\"\n```\n\n**Important:** Double-check your ruleset's required status checks. You cannot specify different required status checks for a merge queue so you need to ensure they work in both cases. A skipped job (such as when the `if` condition is not met) is considered a successful check for this purpose.\n\n### Enable squash merges for the repository\n\nBecause a merge queue takes all commits from the temporary branch and merges them into `HEAD`, it's important to squash pull requests[^squash-pull-requests] before they are merged. That ensures each pull request adds a single commit to `HEAD`, which makes individual pull requests much easier to revert if necessary. To do that:\n\n1. Go to the repository settings page\n2. Scroll down to the Pull Requests section\n3. Check the box next to \"Allow squash merges\"\n4. Uncheck the other merge types to avoid confusion\n\nThis matters because the merge queue can use only merge strategies that are enabled for the repository.\n\n### Enable the merge queue with a ruleset\n\nMerge queues can be enabled only through a ruleset applied to a branch. You can add a merge queue to an existing ruleset or create a new one. Here are the steps:\n\n1. Go to the repository settings page\n2. On the left navigation, click \"Rules\" and then \"Rulesets\".\n3. Click on an existing ruleset or create a new one.\n4. Scroll down and check the box next to \"Require merge queue\".\n\nThere are several merge queue settings you can customize for your use case:\n\n* **Build concurrency:** The maximum number of queued pull requests running checks at the same time.\n* **Minimum group size:** The minimum number of queued pull requests required before a temporary branch is created to test them together. This is set to 1 by default; otherwise, a single queued pull request could get stuck waiting for others. Consider increasing this only in a high-velocity repository where you want to throttle temporary branch creation.\n* **Maximum group size:** The maximum number of queued pull requests to include in a single temporary branch. The default is 5, which strikes a good balance between being too small, which creates more temporary branches, and being too large, which increases the likelihood of a failure as more pull requests must work together.\n* **Wait time to meet minimum group size:** The number of minutes to wait for the minimum group size to be met. The default is five minutes, which means GitHub waits up to five minutes to see whether the minimum group size is reached. If it is not, GitHub starts merging queued pull requests anyway. This backstop keeps queued pull requests from waiting too long before moving to a temporary branch.\n* **Require all queue entries to pass required checks:** When checked, which is the default, each queued pull request must pass status checks after being added to the temporary branch on top of the preceding pull requests. When unchecked, only the `HEAD` pull request on the temporary branch must pass status checks. Checking only `HEAD` provides faster feedback and uses fewer resources, but it also makes failures harder to diagnose because you do not immediately know which pull request caused the problem.\n* **Status check timeout:** The number of minutes GitHub waits for status checks to complete for queued pull requests. If status checks take longer than this limit, GitHub assumes they failed. This prevents queued pull requests from waiting indefinitely for checks that will never complete.\n\nBe sure to click \"Save changes\" at the bottom of the page whenever you edit these settings.\n\n## Example\n\nAssume you're using the default settings for a merge queue on the `main` branch and there are seven pull requests, numbered 1 through 7, that have passed CI and are ready to be added to the merge queue. The developer clicks the \"Merge when ready\" button at the bottom of each pull request to add them, in order, to the queue. The merge queue looks like this:\n\n1. Pull request 1\n1. Pull request 2\n1. Pull request 3\n1. Pull request 4\n1. Pull request 5\n1. Pull request 6\n1. Pull request 7\n\nBecause the minimum group size of 1 has been met, GitHub creates a temporary branch and squashes pull request 1's commits into it. Pull request 1's status checks run, and because they pass, pull request 2's commits are squashed into the temporary branch. Its status checks also pass, so pull request 3's commits are squashed into the branch. Unfortunately, pull request 3's status checks fail. The pull request on GitHub is marked as failed, and the squashed commit is removed from the temporary branch. Pull requests 1 and 2 are merged into `main` and closed. The merge queue now looks like this:\n\n1. Pull request 4\n1. Pull request 5\n1. Pull request 6\n1. Pull request 7\n\nPull request 3 has been removed from the queue pending developer intervention to fix the failing status checks. A new temporary branch is created, and pull request 4's commits are squashed into it. It turns out that fixing pull request 3 is fairly easy, so the developer clicks \"Merge when ready\" again. The merge queue now looks like this:\n\n1. Pull request 5\n1. Pull request 6\n1. Pull request 7\n1. Pull request 3\n\nThe remaining pull requests are then added to the temporary branch one by one so their status checks can run. This time, all five pull requests pass their checks, so they are all merged into `main`.\n\n## Conclusion\n\nThe GitHub merge queue is one of those features that sounds like a small quality-of-life improvement until you start using it and realize how much time you were spending babysitting pull requests. By automating the \"update and wait\" cycle, it frees developers to focus on writing code instead of monitoring CI dashboards. The setup is straightforward: add the `merge_group` trigger to your CI workflow, enable squash merges, and turn on the merge queue through a ruleset. From there, the defaults work well for most teams, and the configurable settings give you room to tune behavior as your repository's velocity grows. If your team spends meaningful time managing pull request ordering or waiting for CI to clear, the merge queue is worth enabling.\n\n[^merge-group-trigger]: [Events that trigger workflows](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group)\n[^squash-pull-requests]: [Configuring commit squashing for pull requests](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests?versionId=free-pro-team%40latest&productId=actions&restPage=reference%2Cworkflows-and-actions%2Cevents-that-trigger-workflows)\n","content_html":"<p>Imagine this: you’re working at a company that uses GitHub as its source control platform. Each repository follows established best practices, such as requiring continuous integration (CI) tests to pass before a pull request can be merged. Branch protection rules maintain a linear commit history and require pull requests to be approved before merging. Developers may merge their own pull requests once CI passes and they have the required approvals.</p>\n<p>The linear commit history requirement means that each pull request must be tested on top of <code>HEAD</code> in CI before it can be merged. GitHub provides an “Update Branch” button on pull requests for this purpose. As a developer, you click “Update Branch” and wait for CI to pass again.</p>\n<p>Unfortunately, CI takes ten minutes to run, so you step away for a bathroom break and a snack. When you get back to your desk, CI has passed, but the “Update Branch” button is enabled again. In the time it took CI to finish, someone else merged a pull request, so you have to start the entire process over.</p>\n<p>The situation is frustrating with just one pull request, so imagine what happens if you and other engineers often have more than one open at a time. That means jumping back and forth between pull requests, repeatedly clicking “Update Branch,” and waiting to see whether this is the time you actually make it through before someone else merges a different pull request.</p>\n<p>In situations like this, the GitHub merge queue can free up developer time by eliminating the babysitting of pull requests.</p>\n<h2 id="what-does-a-github-merge-queue-do">What does a GitHub merge queue do?</h2>\n<p>A GitHub merge queue acts as an intermediate step between approving a pull request and landing its commit on the target branch. Instead of merging a pull request as soon as it’s ready, you add it to the merge queue. The queue collects pending pull requests and tests each one on top of the others, up to a maximum batch size of five by default. You can configure the same CI tests to run for the merge queue, and pull requests are kicked back to their authors if those tests fail.</p>\n<p>Behind the scenes, GitHub waits until the maximum batch size is available, unless a configurable timeout is reached, and then adds the pull requests to a temporary branch based on <code>HEAD</code> in queue order. CI runs for each pull request as it is added to the temporary branch, and the next pull request is added only after the previous one’s CI checks pass. If a pull request fails CI, it is removed from the queue for further review by the author. The original pull request remains open on GitHub until it is successfully merged through the merge queue. The temporary branch containing the previously passing pull requests is merged into <code>HEAD</code>, and a new temporary branch starts with the pull request immediately after the failing one. The process then continues.</p>\n<p>Once GitHub has a temporary branch where all pull requests have passed CI, it merges those commits into <code>HEAD</code> in a single operation. The commits land in the same order they appeared in the merge queue.</p>\n<p>The biggest advantage of this approach is that every pull request is automatically tested on top of all the pull requests that came before it in the queue. You never have to click “Update Branch” because that effectively happens as part of the merge queue process. CI now runs twice: once before the pull request is added to the queue and again during temporary branch creation. That dramatically reduces the manual work required to land a pull request on <code>HEAD</code>.</p>\n<p>Another advantage is that the merge queue is editable. You can reorder pull requests or remove them from the queue before they are merged, giving you full control over which pull requests move forward and which ones wait.</p>\n<h2 id="setting-up-a-github-merge-queue">Setting up a GitHub merge queue</h2>\n<p>To set up a merge queue for a repository, there are three steps:</p>\n<ol>\n<li>Ensure your CI tests run in the merge queue</li>\n<li>Enable squash merges for the repository</li>\n<li>Enable the merge queue with a ruleset</li>\n</ol>\n<p>Each step is important for the overall operation of the merge queue.</p>\n<h3 id="ensure-your-ci-tests-run-in-the-merge-queue">Ensure your CI tests run in the merge queue</h3>\n<p>The first step in setting up a GitHub merge queue is configuring CI for the queue. You can do that by adding the <code>merge_group</code> trigger<sup><a href="#user-content-fn-merge-group-trigger" id="user-content-fnref-merge-group-trigger" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> to the same GitHub workflow file that runs CI for pull requests:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #79B8FF">on</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">pull_request</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">branches</span><span style="color: #E1E4E8">: [</span><span style="color: #9ECBFF">main</span><span style="color: #E1E4E8">]</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">merge_group</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">branches</span><span style="color: #E1E4E8">: [</span><span style="color: #9ECBFF">main</span><span style="color: #E1E4E8">]</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">types</span><span style="color: #E1E4E8">: [</span><span style="color: #9ECBFF">checks_requested</span><span style="color: #E1E4E8">]</span></span></code></pre>\n<p>This ensures you’re running the same checks when a pull request is opened or updated and when a merge queue group is tested. As of this writing, <code>checks_requested</code> is the only available <code>merge_group</code> type.</p>\n<p>You should also review the jobs in your CI workflow to make sure they all make sense to run on the merge queue branch. The merge queue CI process won’t have access to pull request-specific information, such as the pull request title or pull request branch name. You can scope jobs to not run for the merge queue using an <code>if</code> condition, like this:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #85E89D">jobs</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">lint</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">if</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">github.event_name != 'merge_group'</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">runs-on</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">ubuntu-latest</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">steps</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> - </span><span style="color: #85E89D">run</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">echo "linting..."</span></span></code></pre>\n<p>Alternately, you can check the current branch name to see if it’s a merge queue branch, which exists under <code>refs/head/gh-readonly-queue/</code>:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #85E89D">jobs</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">lint</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">if</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">${{ !startsWith(github.ref, 'refs/heads/gh-readonly-queue/') }}</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">runs-on</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">ubuntu-latest</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #85E89D">steps</span><span style="color: #E1E4E8">:</span></span>\n<span class="line"><span style="color: #E1E4E8"> - </span><span style="color: #85E89D">run</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">echo "linting..."</span></span></code></pre>\n<p><strong>Important:</strong> Double-check your ruleset’s required status checks. You cannot specify different required status checks for a merge queue so you need to ensure they work in both cases. A skipped job (such as when the <code>if</code> condition is not met) is considered a successful check for this purpose.</p>\n<h3 id="enable-squash-merges-for-the-repository">Enable squash merges for the repository</h3>\n<p>Because a merge queue takes all commits from the temporary branch and merges them into <code>HEAD</code>, it’s important to squash pull requests<sup><a href="#user-content-fn-squash-pull-requests" id="user-content-fnref-squash-pull-requests" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup> before they are merged. That ensures each pull request adds a single commit to <code>HEAD</code>, which makes individual pull requests much easier to revert if necessary. To do that:</p>\n<ol>\n<li>Go to the repository settings page</li>\n<li>Scroll down to the Pull Requests section</li>\n<li>Check the box next to “Allow squash merges”</li>\n<li>Uncheck the other merge types to avoid confusion</li>\n</ol>\n<p>This matters because the merge queue can use only merge strategies that are enabled for the repository.</p>\n<h3 id="enable-the-merge-queue-with-a-ruleset">Enable the merge queue with a ruleset</h3>\n<p>Merge queues can be enabled only through a ruleset applied to a branch. You can add a merge queue to an existing ruleset or create a new one. Here are the steps:</p>\n<ol>\n<li>Go to the repository settings page</li>\n<li>On the left navigation, click “Rules” and then “Rulesets”.</li>\n<li>Click on an existing ruleset or create a new one.</li>\n<li>Scroll down and check the box next to “Require merge queue”.</li>\n</ol>\n<p>There are several merge queue settings you can customize for your use case:</p>\n<ul>\n<li><strong>Build concurrency:</strong> The maximum number of queued pull requests running checks at the same time.</li>\n<li><strong>Minimum group size:</strong> The minimum number of queued pull requests required before a temporary branch is created to test them together. This is set to 1 by default; otherwise, a single queued pull request could get stuck waiting for others. Consider increasing this only in a high-velocity repository where you want to throttle temporary branch creation.</li>\n<li><strong>Maximum group size:</strong> The maximum number of queued pull requests to include in a single temporary branch. The default is 5, which strikes a good balance between being too small, which creates more temporary branches, and being too large, which increases the likelihood of a failure as more pull requests must work together.</li>\n<li><strong>Wait time to meet minimum group size:</strong> The number of minutes to wait for the minimum group size to be met. The default is five minutes, which means GitHub waits up to five minutes to see whether the minimum group size is reached. If it is not, GitHub starts merging queued pull requests anyway. This backstop keeps queued pull requests from waiting too long before moving to a temporary branch.</li>\n<li><strong>Require all queue entries to pass required checks:</strong> When checked, which is the default, each queued pull request must pass status checks after being added to the temporary branch on top of the preceding pull requests. When unchecked, only the <code>HEAD</code> pull request on the temporary branch must pass status checks. Checking only <code>HEAD</code> provides faster feedback and uses fewer resources, but it also makes failures harder to diagnose because you do not immediately know which pull request caused the problem.</li>\n<li><strong>Status check timeout:</strong> The number of minutes GitHub waits for status checks to complete for queued pull requests. If status checks take longer than this limit, GitHub assumes they failed. This prevents queued pull requests from waiting indefinitely for checks that will never complete.</li>\n</ul>\n<p>Be sure to click “Save changes” at the bottom of the page whenever you edit these settings.</p>\n<h2 id="example">Example</h2>\n<p>Assume you’re using the default settings for a merge queue on the <code>main</code> branch and there are seven pull requests, numbered 1 through 7, that have passed CI and are ready to be added to the merge queue. The developer clicks the “Merge when ready” button at the bottom of each pull request to add them, in order, to the queue. The merge queue looks like this:</p>\n<ol>\n<li>Pull request 1</li>\n<li>Pull request 2</li>\n<li>Pull request 3</li>\n<li>Pull request 4</li>\n<li>Pull request 5</li>\n<li>Pull request 6</li>\n<li>Pull request 7</li>\n</ol>\n<p>Because the minimum group size of 1 has been met, GitHub creates a temporary branch and squashes pull request 1’s commits into it. Pull request 1’s status checks run, and because they pass, pull request 2’s commits are squashed into the temporary branch. Its status checks also pass, so pull request 3’s commits are squashed into the branch. Unfortunately, pull request 3’s status checks fail. The pull request on GitHub is marked as failed, and the squashed commit is removed from the temporary branch. Pull requests 1 and 2 are merged into <code>main</code> and closed. The merge queue now looks like this:</p>\n<ol>\n<li>Pull request 4</li>\n<li>Pull request 5</li>\n<li>Pull request 6</li>\n<li>Pull request 7</li>\n</ol>\n<p>Pull request 3 has been removed from the queue pending developer intervention to fix the failing status checks. A new temporary branch is created, and pull request 4’s commits are squashed into it. It turns out that fixing pull request 3 is fairly easy, so the developer clicks “Merge when ready” again. The merge queue now looks like this:</p>\n<ol>\n<li>Pull request 5</li>\n<li>Pull request 6</li>\n<li>Pull request 7</li>\n<li>Pull request 3</li>\n</ol>\n<p>The remaining pull requests are then added to the temporary branch one by one so their status checks can run. This time, all five pull requests pass their checks, so they are all merged into <code>main</code>.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>The GitHub merge queue is one of those features that sounds like a small quality-of-life improvement until you start using it and realize how much time you were spending babysitting pull requests. By automating the “update and wait” cycle, it frees developers to focus on writing code instead of monitoring CI dashboards. The setup is straightforward: add the <code>merge_group</code> trigger to your CI workflow, enable squash merges, and turn on the merge queue through a ruleset. From there, the defaults work well for most teams, and the configurable settings give you room to tune behavior as your repository’s velocity grows. If your team spends meaningful time managing pull request ordering or waiting for CI to clear, the merge queue is worth enabling.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-merge-group-trigger">\n<p><a href="https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#merge_group">Events that trigger workflows</a> <a href="#user-content-fnref-merge-group-trigger" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-squash-pull-requests">\n<p><a href="https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/configuring-commit-squashing-for-pull-requests?versionId=free-pro-team%40latest&#x26;productId=actions&#x26;restPage=reference%2Cworkflows-and-actions%2Cevents-that-trigger-workflows">Configuring commit squashing for pull requests</a> <a href="#user-content-fnref-squash-pull-requests" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n</ol>\n</section>","tags":["GitHub","Git","Merge Queue","CI"],"date_published":"2026-04-06T00:00:00.000Z","date_updated":"2026-04-06T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2026/03/proxying-fetch-requests-server-side-javascript/","url":"https://humanwhocodes.com/blog/2026/03/proxying-fetch-requests-server-side-javascript/","title":"Proxying fetch requests in server-side JavaScript","author":{"name":"Nicholas C. Zakas"},"summary":"Learn how to proxy fetch() requests in Node.js, Deno, Bun, and Cloudflare Workers to better monitor and control your server-side traffic.","content_text":"\nIf you retrieve content from the internet, you'll eventually need to proxy requests. Proxying is useful for logging traffic, modifying headers, altering content, improving performance through caching, or hiding an originating IP address. Most server-side JavaScript runtimes allow you to proxy requests using `fetch()`.\n\nThe Fetch standard[^1] doesn't specify request proxying because it's a browser-focused API. Consequently, server-side runtimes implement proxying differently.\n\n## Node.js\n\nNode.js natively supports proxying `fetch()` requests through environment variables as of Node.js v22.21.0 and v24.5.0[^2]. You can set the `HTTP_PROXY` and `HTTPS_PROXY` environment variables to specify the proxy server for HTTP and HTTPS requests, respectively:\n\n```shell\n# Enable Node.js to use environment variables for proxying\nexport NODE_USE_ENV_PROXY=1\n\nexport HTTP_PROXY=http://username:password@proxy-server.com:8080\nexport HTTPS_PROXY=https://username:password@proxy-server.com:8080\n```\n\nThe `NODE_USE_ENV_PROXY` variable is required to enable this behavior, as it is disabled by default to avoid unintended proxying. You can also use the `--use-env-proxy` flag when running your Node.js application to enable this feature without setting the environment variable:\n\n```shell\nnode --use-env-proxy your-app.js\n```\n\nYou can also proxy specific requests programmatically. While the Node.js `fetch()` API doesn't natively support proxying, it's built on top of the `undici` package[^3], which does. Since Node.js doesn't expose the `ProxyAgent` class[^4] directly, you'll first need to install `undici`:\n\n```shell\nnpm i undici\n```\n\nTo use a proxy, create a `ProxyAgent` instance and pass it as the `dispatcher` option:\n\n```js\nimport { ProxyAgent } from 'undici';\n\nconst agent = new ProxyAgent('http://username:password@proxy-server.com:8080');\n\nconst response = await fetch('https://api.example.com', {\n dispatcher: agent\n});\n\nconst body = await response.json();\n```\n\n## Deno\n\nDeno's `fetch()` uses the `client` property in the options object to specify a proxy client:\n\n```js\nconst client = Deno.createHttpClient({\n proxy: { url: \"http://username:password@proxy-server.com:8080\" },\n});\n\nconst response = await fetch(\"https://api.example.com\", { client });\nconst data = await response.json();\n\nclient.close(); // Remember to close the client when done\n```\n\nDespite its name, `Deno.createHttpClient()` also supports HTTPS proxies:\n\n```js\nconst client = Deno.createHttpClient({\n proxy: { url: \"https://username:password@proxy-server.com:8080\" },\n});\n\nconst response = await fetch(\"https://api.example.com\", { client });\nconst data = await response.json();\n\nclient.close(); // Remember to close the client when done\n```\n\n## Bun\n\nBun provides native support for `fetch()` proxying via the `proxy` property:\n\n```js\nconst response = await fetch(\"https://api.example.com\", {\n proxy: \"http://username:password@proxy-server.com:8080\"\n});\n\nconst body = await response.json();\n```\n\n## Cloudflare Workers\n\nThe Cloudflare Workers runtime does not natively support proxying `fetch()` requests through environment variables or programmatic options. However, you can work around this by using a Node.js Docker container to handle the requests.\n\nThe `@humanwhocodes/proxy-fetch-server`[^5] package is a small utility I created to simplify this. Here’s how to run it in a container:\n\n```dockerfile\nFROM node:22-slim\n\nWORKDIR /app\nRUN npm install -g @humanwhocodes/proxy-fetch-server@2\n\nEXPOSE 8080\nENV PORT=8080\n\nCMD [\"npx\", \"@humanwhocodes/proxy-fetch-server\"]\n```\n\nNext, define a container class:\n\n```js\nimport { Container } from \"@cloudflare/containers\";\n\nexport class ProxyFetchContainer extends Container {\n defaultPort = 8080;\n}\n```\n\nUpdate your `wrangler.jsonc` file to include the binding:\n\n```jsonc\n{\n \"name\": \"proxy-fetcher\",\n\n \"containers\": [\n {\n \"class_name\": \"ProxyFetchContainer\",\n \"image\": \"./Dockerfile\"\n }\n ],\n \"durable_objects\": {\n \"bindings\": [\n {\n \"name\": \"PROXY_FETCH_CONTAINER\",\n \"class_name\": \"ProxyFetchContainer\"\n }\n ]\n },\n \"migrations\": [\n {\n \"tag\": \"v1\",\n \"new_sqlite_classes\": [\n \"ProxyFetchContainer\"\n ]\n }\n ],\n}\n```\n\nFinally, access the proxy container in your code:\n\n```js\n// get and start container\nconst container = env.PROXY_FETCH_CONTAINER.getByName(\"proxy-fetch-server\");\n\nawait container.startAndWaitForPorts({\n startOptions: {\n envVars: {\n FETCH_PROXY: \"http://username:password@proxy-server.com:8080\"\n }\n }\n});\n\n// Make request to the container\nconst containerResponse = await container.fetch(\n new Request(\"http://container/\", {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application/json\"\n },\n body: JSON.stringify({ url })\n })\n);\n```\n\nWhile this requires more setup than other runtimes, it's a reliable solution for this use case.\n\n## Conclusion\n\nProxying `fetch()` requests is a common requirement in server-side development, whether for security, monitoring, or performance. While runtimes like Deno and Bun offer straightforward programmatic APIs, others like Node.js and Cloudflare Workers require a bit more legwork. Regardless of your choice, understanding these patterns ensures your applications can communicate reliably with the outside world. Give these methods a try in your next project; you'll find that handling proxies is just another essential tool in your server-side JavaScript toolkit.\n\n**Update(2026-03-04):** Added information about Node.js support for proxy-related environment variables.\n\n[^1]: [Fetch Standard](https://fetch.spec.whatwg.org/)\n[^2]: [Node.js Enterprise Network Configuration](https://nodejs.org/en/learn/http/enterprise-network-configuration)\n[^3]: [Undici](https://undici.nodejs.org)\n[^4]: [Issue #43187: Expose Undici ProxyAgent](https://github.com/nodejs/node/issues/43187)\n[^5]: [`@humanwhocodes/proxy-fetch-server`](https://npmjs.com/package/@humanwhocodes/proxy-fetch-server)\n","content_html":"<p>If you retrieve content from the internet, you’ll eventually need to proxy requests. Proxying is useful for logging traffic, modifying headers, altering content, improving performance through caching, or hiding an originating IP address. Most server-side JavaScript runtimes allow you to proxy requests using <code>fetch()</code>.</p>\n<p>The Fetch standard<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> doesn’t specify request proxying because it’s a browser-focused API. Consequently, server-side runtimes implement proxying differently.</p>\n<h2 id="nodejs">Node.js</h2>\n<p>Node.js natively supports proxying <code>fetch()</code> requests through environment variables as of Node.js v22.21.0 and v24.5.0<sup><a href="#user-content-fn-2" id="user-content-fnref-2" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup>. You can set the <code>HTTP_PROXY</code> and <code>HTTPS_PROXY</code> environment variables to specify the proxy server for HTTP and HTTPS requests, respectively:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #6A737D"># Enable Node.js to use environment variables for proxying</span></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> NODE_USE_ENV_PROXY</span><span style="color: #F97583">=</span><span style="color: #79B8FF">1</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> HTTP_PROXY</span><span style="color: #F97583">=</span><span style="color: #9ECBFF">http://username:password@proxy-server.com:8080</span></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> HTTPS_PROXY</span><span style="color: #F97583">=</span><span style="color: #9ECBFF">https://username:password@proxy-server.com:8080</span></span></code></pre>\n<p>The <code>NODE_USE_ENV_PROXY</code> variable is required to enable this behavior, as it is disabled by default to avoid unintended proxying. You can also use the <code>--use-env-proxy</code> flag when running your Node.js application to enable this feature without setting the environment variable:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">node</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">--use-env-proxy</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">your-app.js</span></span></code></pre>\n<p>You can also proxy specific requests programmatically. While the Node.js <code>fetch()</code> API doesn’t natively support proxying, it’s built on top of the <code>undici</code> package<sup><a href="#user-content-fn-3" id="user-content-fnref-3" data-footnote-ref="" aria-describedby="footnote-label">3</a></sup>, which does. Since Node.js doesn’t expose the <code>ProxyAgent</code> class<sup><a href="#user-content-fn-4" id="user-content-fnref-4" data-footnote-ref="" aria-describedby="footnote-label">4</a></sup> directly, you’ll first need to install <code>undici</code>:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npm</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">i</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">undici</span></span></code></pre>\n<p>To use a proxy, create a <code>ProxyAgent</code> instance and pass it as the <code>dispatcher</code> option:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">import</span><span style="color: #E1E4E8"> { ProxyAgent } </span><span style="color: #F97583">from</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">'undici'</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">agent</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">new</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">ProxyAgent</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">'http://username:password@proxy-server.com:8080'</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">response</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">'https://api.example.com'</span><span style="color: #E1E4E8">, {</span></span>\n<span class="line"><span style="color: #E1E4E8"> dispatcher: agent</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">body</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> response.</span><span style="color: #B392F0">json</span><span style="color: #E1E4E8">();</span></span></code></pre>\n<h2 id="deno">Deno</h2>\n<p>Deno’s <code>fetch()</code> uses the <code>client</code> property in the options object to specify a proxy client:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">client</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> Deno.</span><span style="color: #B392F0">createHttpClient</span><span style="color: #E1E4E8">({</span></span>\n<span class="line"><span style="color: #E1E4E8"> proxy: { url: </span><span style="color: #9ECBFF">"http://username:password@proxy-server.com:8080"</span><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">response</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"https://api.example.com"</span><span style="color: #E1E4E8">, { client });</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">data</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> response.</span><span style="color: #B392F0">json</span><span style="color: #E1E4E8">();</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8">client.</span><span style="color: #B392F0">close</span><span style="color: #E1E4E8">(); </span><span style="color: #6A737D">// Remember to close the client when done</span></span></code></pre>\n<p>Despite its name, <code>Deno.createHttpClient()</code> also supports HTTPS proxies:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">client</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> Deno.</span><span style="color: #B392F0">createHttpClient</span><span style="color: #E1E4E8">({</span></span>\n<span class="line"><span style="color: #E1E4E8"> proxy: { url: </span><span style="color: #9ECBFF">"https://username:password@proxy-server.com:8080"</span><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">response</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"https://api.example.com"</span><span style="color: #E1E4E8">, { client });</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">data</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> response.</span><span style="color: #B392F0">json</span><span style="color: #E1E4E8">();</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8">client.</span><span style="color: #B392F0">close</span><span style="color: #E1E4E8">(); </span><span style="color: #6A737D">// Remember to close the client when done</span></span></code></pre>\n<h2 id="bun">Bun</h2>\n<p>Bun provides native support for <code>fetch()</code> proxying via the <code>proxy</code> property:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">response</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"https://api.example.com"</span><span style="color: #E1E4E8">, {</span></span>\n<span class="line"><span style="color: #E1E4E8"> proxy: </span><span style="color: #9ECBFF">"http://username:password@proxy-server.com:8080"</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">body</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> response.</span><span style="color: #B392F0">json</span><span style="color: #E1E4E8">();</span></span></code></pre>\n<h2 id="cloudflare-workers">Cloudflare Workers</h2>\n<p>The Cloudflare Workers runtime does not natively support proxying <code>fetch()</code> requests through environment variables or programmatic options. However, you can work around this by using a Node.js Docker container to handle the requests.</p>\n<p>The <code>@humanwhocodes/proxy-fetch-server</code><sup><a href="#user-content-fn-5" id="user-content-fnref-5" data-footnote-ref="" aria-describedby="footnote-label">5</a></sup> package is a small utility I created to simplify this. Here’s how to run it in a container:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">FROM</span><span style="color: #E1E4E8"> node:22-slim</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">WORKDIR</span><span style="color: #E1E4E8"> /app</span></span>\n<span class="line"><span style="color: #F97583">RUN</span><span style="color: #E1E4E8"> npm install -g @humanwhocodes/proxy-fetch-server@2</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">EXPOSE</span><span style="color: #E1E4E8"> 8080</span></span>\n<span class="line"><span style="color: #F97583">ENV</span><span style="color: #E1E4E8"> PORT=8080</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">CMD</span><span style="color: #E1E4E8"> [</span><span style="color: #9ECBFF">"npx"</span><span style="color: #E1E4E8">, </span><span style="color: #9ECBFF">"@humanwhocodes/proxy-fetch-server"</span><span style="color: #E1E4E8">]</span></span></code></pre>\n<p>Next, define a container class:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">import</span><span style="color: #E1E4E8"> { Container } </span><span style="color: #F97583">from</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"@cloudflare/containers"</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">class</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">ProxyFetchContainer</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">extends</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Container</span><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #FFAB70">defaultPort</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">8080</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>Update your <code>wrangler.jsonc</code> file to include the binding:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">{</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"name"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"proxy-fetcher"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"containers"</span><span style="color: #E1E4E8">: [</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"class_name"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"ProxyFetchContainer"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"image"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"./Dockerfile"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> ],</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"durable_objects"</span><span style="color: #E1E4E8">: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"bindings"</span><span style="color: #E1E4E8">: [</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"name"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"PROXY_FETCH_CONTAINER"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"class_name"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"ProxyFetchContainer"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> ]</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"migrations"</span><span style="color: #E1E4E8">: [</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"tag"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"v1"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"new_sqlite_classes"</span><span style="color: #E1E4E8">: [</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"ProxyFetchContainer"</span></span>\n<span class="line"><span style="color: #E1E4E8"> ]</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> ],</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>Finally, access the proxy container in your code:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #6A737D">// get and start container</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">container</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> env.</span><span style="color: #79B8FF">PROXY_FETCH_CONTAINER</span><span style="color: #E1E4E8">.</span><span style="color: #B392F0">getByName</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"proxy-fetch-server"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">await</span><span style="color: #E1E4E8"> container.</span><span style="color: #B392F0">startAndWaitForPorts</span><span style="color: #E1E4E8">({</span></span>\n<span class="line"><span style="color: #E1E4E8"> startOptions: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> envVars: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> FETCH_PROXY: </span><span style="color: #9ECBFF">"http://username:password@proxy-server.com:8080"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #6A737D">// Make request to the container</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">containerResponse</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> container.</span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">new</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Request</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"http://container/"</span><span style="color: #E1E4E8">, {</span></span>\n<span class="line"><span style="color: #E1E4E8"> method: </span><span style="color: #9ECBFF">"POST"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> headers: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"Content-Type"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"application/json"</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> body: </span><span style="color: #79B8FF">JSON</span><span style="color: #E1E4E8">.</span><span style="color: #B392F0">stringify</span><span style="color: #E1E4E8">({ url })</span></span>\n<span class="line"><span style="color: #E1E4E8"> })</span></span>\n<span class="line"><span style="color: #E1E4E8">);</span></span></code></pre>\n<p>While this requires more setup than other runtimes, it’s a reliable solution for this use case.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>Proxying <code>fetch()</code> requests is a common requirement in server-side development, whether for security, monitoring, or performance. While runtimes like Deno and Bun offer straightforward programmatic APIs, others like Node.js and Cloudflare Workers require a bit more legwork. Regardless of your choice, understanding these patterns ensures your applications can communicate reliably with the outside world. Give these methods a try in your next project; you’ll find that handling proxies is just another essential tool in your server-side JavaScript toolkit.</p>\n<p><strong>Update(2026-03-04):</strong> Added information about Node.js support for proxy-related environment variables.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-1">\n<p><a href="https://fetch.spec.whatwg.org/">Fetch Standard</a> <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-2">\n<p><a href="https://nodejs.org/en/learn/http/enterprise-network-configuration">Node.js Enterprise Network Configuration</a> <a href="#user-content-fnref-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-3">\n<p><a href="https://undici.nodejs.org">Undici</a> <a href="#user-content-fnref-3" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-4">\n<p><a href="https://github.com/nodejs/node/issues/43187">Issue #43187: Expose Undici ProxyAgent</a> <a href="#user-content-fnref-4" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-5">\n<p><a href="https://npmjs.com/package/@humanwhocodes/proxy-fetch-server"><code>@humanwhocodes/proxy-fetch-server</code></a> <a href="#user-content-fnref-5" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n</ol>\n</section>","tags":["Fetch","Node.js","Cloudflare","Proxy"],"date_published":"2026-03-03T00:00:00.000Z","date_updated":"2026-03-04T00:00:00.000Z"},{"id":"https://humanwhocodes.com/snippets/2026/02/using-your-own-supabase-signing-keys/","url":"https://humanwhocodes.com/snippets/2026/02/using-your-own-supabase-signing-keys/","title":"Using your own Supabase signing keys","author":{"name":"Nicholas C. Zakas"},"summary":"Supabase generates JWT signing keys automatically, but you can also use your own if you want to share keys across multiple instances or generate tokens manually.","content_text":"\n[Supabase](https://supabase.com) uses JWT signing keys to sign authentication tokens. By default, Supabase generates a new signing key on startup, but you can also use your own signing keys. This is useful if you want to generate your own tokens or if you want to use the same signing keys across multiple Supabase instances.\n\n## Generate a signing key\n\nFirst, generate a new signing key using the Supabase CLI:\n\n```shell\nnpx supabase gen signing-key --algorithm ES256\n```\n\nThis will output a new signing key in JSON format to the terminal.\n\n**Note:** If you already have a `supabase/signing_key.json` file, the CLI will ask if you want to overwrite it. If you want to keep the existing signing key, you can choose \"No\" and the CLI will not output a new signing key.\n\n## Local Development\n\nFor local development, save the signing key in your `supabase` directory, such as `supabase/signing_key.json`. Supabase requires the local signing key to be contained in an array, so you need to wrap the output in square brackets. For example, if your output looks like this:\n\n```json\n{\n \"kty\": \"EC\",\n \"d\": \"N8sXo9n2e5Z19sXo9n2e5Z1\",\n \"use\": \"sig\",\n \"crv\": \"P-256\",\n \"kid\": \"my-key-id\",\n \"x\": \"f83OJ3D2xF4\",\n \"y\": \"x_FEzRu9c\"\n}\n```\n\nYou need to wrap it like this:\n\n```json\n[\n {\n \"kty\": \"EC\",\n \"d\": \"N8sXo9n2e5Z19sXo9n2e5Z1\",\n \"use\": \"sig\",\n \"crv\": \"P-256\",\n \"kid\": \"my-key-id\",\n \"x\": \"f83OJ3D2xF4\",\n \"y\": \"x_FEzRu9c\"\n }\n]\n```\n\nSave this into a file called `supabase/signing_key.json`.\n\nThen, edit the `config.toml` file and add the following lines to the `[auth]` section:\n\n```toml\n[auth]\nsigning_keys_path = \"./signing_key.json\"\n```\n\nThis will tell Supabase to use your signing key instead of generating a new one on startup. After editing `config.toml`, you need to restart Supabase to reload the configuration:\n\n```shell\nnpx supabase stop\nnpx supabase start\n```\n\n## Hosted Supabase\n\nIf you are using the hosted version of Supabase, you can set the signing keys in the Supabase dashboard. Go to the \"Settings\" tab, then click on \"JWT Signing Keys\".\n\nIf you already have a standby key, you'll need to remove it before you can add a new one. To remove a standby key, click the three dots next to the key and select \"Move to previously used\". After removing the existing standby key, you can add your new signing key as described above.\n\n**Important:** This signing key must *not* by in an array. It should be the raw JSON object that was generated by the Supabase CLI. \n\nClick \"Create Standby Key\". In the dialog select \"Import an existing key\" and paste in your previously generated signing key. Click the \"Create Standby Key\" button to save the new signing key.\n\nClick \"Rotate Keys\" to make the new signing key active. This will rotate the keys and make the new signing key the active key for signing tokens.\n\n## Important Notes\n\n* The Supabase CLI-generated signing key contains both `verify` and `sign` keys because Supabase itself needs to do both. However, some tools like [`jose`](https://npmjs.com/package/jose) will fail signing if object contains a `verify` key. If you encounter this issue, you can remove the `verify` key from the signing key JSON file before using it with `jose`.\n* If your app has users with a persisted session, changing the signing key will invalidate all existing tokens. This means that users will need to log in again to obtain new tokens signed with the new key. Make sure to communicate this change to your users if you are changing the signing key in a production environment. If you're using the JavaScript client, you can call `supabase.auth.refreshSession()` to refresh the session and obtain a new token without requiring the user to log in again.\n* You can tell if a user has an invalid JWT by checking the `error` property of the user object returned by `supabase.auth.getUser()`. If the JWT is invalid, the `error` property will contain a `code` property of `\"bad_jwt\"`.\n\n ","content_html":"<p><a href="https://supabase.com">Supabase</a> uses JWT signing keys to sign authentication tokens. By default, Supabase generates a new signing key on startup, but you can also use your own signing keys. This is useful if you want to generate your own tokens or if you want to use the same signing keys across multiple Supabase instances.</p>\n<h2 id="generate-a-signing-key">Generate a signing key</h2>\n<p>First, generate a new signing key using the Supabase CLI:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">gen</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">signing-key</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">--algorithm</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">ES256</span></span></code></pre>\n<p>This will output a new signing key in JSON format to the terminal.</p>\n<p><strong>Note:</strong> If you already have a <code>supabase/signing_key.json</code> file, the CLI will ask if you want to overwrite it. If you want to keep the existing signing key, you can choose “No” and the CLI will not output a new signing key.</p>\n<h2 id="local-development">Local Development</h2>\n<p>For local development, save the signing key in your <code>supabase</code> directory, such as <code>supabase/signing_key.json</code>. Supabase requires the local signing key to be contained in an array, so you need to wrap the output in square brackets. For example, if your output looks like this:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">{</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"kty"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"EC"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"d"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"N8sXo9n2e5Z19sXo9n2e5Z1"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"use"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"sig"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"crv"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"P-256"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"kid"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"my-key-id"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"x"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"f83OJ3D2xF4"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"y"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"x_FEzRu9c"</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>You need to wrap it like this:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">[</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"kty"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"EC"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"d"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"N8sXo9n2e5Z19sXo9n2e5Z1"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"use"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"sig"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"crv"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"P-256"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"kid"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"my-key-id"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"x"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"f83OJ3D2xF4"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"y"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"x_FEzRu9c"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8">]</span></span></code></pre>\n<p>Save this into a file called <code>supabase/signing_key.json</code>.</p>\n<p>Then, edit the <code>config.toml</code> file and add the following lines to the <code>[auth]</code> section:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">[</span><span style="color: #B392F0">auth</span><span style="color: #E1E4E8">]</span></span>\n<span class="line"><span style="color: #E1E4E8">signing_keys_path = </span><span style="color: #9ECBFF">"./signing_key.json"</span></span></code></pre>\n<p>This will tell Supabase to use your signing key instead of generating a new one on startup. After editing <code>config.toml</code>, you need to restart Supabase to reload the configuration:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">stop</span></span>\n<span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">start</span></span></code></pre>\n<h2 id="hosted-supabase">Hosted Supabase</h2>\n<p>If you are using the hosted version of Supabase, you can set the signing keys in the Supabase dashboard. Go to the “Settings” tab, then click on “JWT Signing Keys”.</p>\n<p>If you already have a standby key, you’ll need to remove it before you can add a new one. To remove a standby key, click the three dots next to the key and select “Move to previously used”. After removing the existing standby key, you can add your new signing key as described above.</p>\n<p><strong>Important:</strong> This signing key must <em>not</em> by in an array. It should be the raw JSON object that was generated by the Supabase CLI.</p>\n<p>Click “Create Standby Key”. In the dialog select “Import an existing key” and paste in your previously generated signing key. Click the “Create Standby Key” button to save the new signing key.</p>\n<p>Click “Rotate Keys” to make the new signing key active. This will rotate the keys and make the new signing key the active key for signing tokens.</p>\n<h2 id="important-notes">Important Notes</h2>\n<ul>\n<li>\n<p>The Supabase CLI-generated signing key contains both <code>verify</code> and <code>sign</code> keys because Supabase itself needs to do both. However, some tools like <a href="https://npmjs.com/package/jose"><code>jose</code></a> will fail signing if object contains a <code>verify</code> key. If you encounter this issue, you can remove the <code>verify</code> key from the signing key JSON file before using it with <code>jose</code>.</p>\n</li>\n<li>\n<p>If your app has users with a persisted session, changing the signing key will invalidate all existing tokens. This means that users will need to log in again to obtain new tokens signed with the new key. Make sure to communicate this change to your users if you are changing the signing key in a production environment. If you’re using the JavaScript client, you can call <code>supabase.auth.refreshSession()</code> to refresh the session and obtain a new token without requiring the user to log in again.</p>\n</li>\n<li>\n<p>You can tell if a user has an invalid JWT by checking the <code>error</code> property of the user object returned by <code>supabase.auth.getUser()</code>. If the JWT is invalid, the <code>error</code> property will contain a <code>code</code> property of <code>"bad_jwt"</code>.</p>\n</li>\n</ul>","tags":["Supabase","JWT","Security"],"date_published":"2026-02-16T00:00:00.000Z","date_updated":"2026-02-16T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2026/02/artifacts-ai-assisted-programming/","url":"https://humanwhocodes.com/blog/2026/02/artifacts-ai-assisted-programming/","title":"The importance of artifacts in AI-assisted programming","author":{"name":"Nicholas C. Zakas"},"summary":"Your AI pair programmer has no memory, which is why proper documentation matters more than ever in AI-assisted development.","content_text":"\nMuch of the hype around AI-assisted programming focuses on \"vibe coding,\" which means working prompt by prompt to build an application without worrying too much about the generated code. As long as something works, that's all that matters. While this approach works well for personal and hobby projects, it's impractical for professional software engineering\n\nProfessional software engineering involves a team of developers working on a shared codebase that's maintained over time. This creates concerns that go beyond whether the code is working. Significant changes need to be documented to provide traceability when something goes wrong. *Traceability* is the ability to look through changes and track them back to their root cause, whether that's a bug fix, a requirements change, or a new feature. Understanding why a change was made, especially one that caused a problem, is essential for maintaining an application over time. That's why professional software organizations prioritize creating artifacts as the application evolves.\n\n## What are artifacts?\n\nAn *artifact* is any output that's created, used, or modified during the software development process. Issues and pull requests are artifacts, as are diagrams, documents, mockups, and the code itself. Most software teams generate a large number of artifacts, which represent an important part of the process. When something goes wrong, artifacts provide traceability to help determine the origin of the problem.\n\nWhen I was learning software development in college, the focus was on front-loading document artifacts to ensure you knew what you were building. We had to create a functional requirements document (FRD, now often called a product requirements document or PRD) describing what the project or feature would do. Then we had to create a technical specification describing the overall design of the code changes. Only once these two documents were complete could we write any code. This is called the *waterfall approach*, where each stage must be completed before the next can begin.\n\nWith agile methodologies becoming more popular, many teams saw this as license to forego the PRDs and tech specs, and instead \"just start coding.\" The focus on iterative development, where software is never truly \"complete,\" meant that these document artifacts took precious time away from the development process. Many teams convinced themselves that two-sentence issue summaries and face-to-face discussions with product managers were enough to implement good software. Documents like PRDs and tech specs became rare in technology companies (outside of high-level architecture and infrastructure discussions, which often had extensive specifications and diagrams). The argument was that if you had a question about why something was done a particular way, you could just ask the person who did it.\n\n## Your AI teammate's forgetfulness\n\nWhen AI-assisted programming began, developers quickly realized that the models didn't always produce reliable results. Far from deterministic, the models may produce wildly different output when prompts aren't specific enough. AI-powered IDEs do their best to provide additional context to the models to make output more reliable, yet developers continue to find that longer prompts produce better results.\n\nHere's the problem: Your AI pair programmer has a very short memory. It can't tell you why it made a decision six months ago that brought down your server today. Human programmers are both implementers and stores of knowledge, while AI is only an implementer. The model doesn't provide traceability beyond the scope of its current context window. If you \"vibe coded\" an implementation and your server goes down, there's no way to tell why. Did the model generate insecure code that left the server vulnerable to attack? If so, why? Did it not know the code had to be secure? Was it something in the original prompt that led it to believe the code didn't need to be secure? There's no way to know what part of the process broke down, which means additional time spent before the problem can be addressed and a higher likelihood of a similar problem in the future.\n\nWith the proper artifacts available, however, the investigation proceeds quickly and systematically. Because some artifacts are used directly as prompts, it's much easier to discover where an ambiguity might have led a model to make an incorrect decision. The type of artifacts you use and the level of detail in each are important for this process.\n\n## Artifacts for AI-assisted programming\n\nWhile there are many different artifacts that can be useful for AI-assisted programming, I’ve found the following to be among the most important:\n\n* Product requirements documents (PRDs) \n* Architectural decision records (ADRs) \n* Technical design documents (TDDs) \n* Task lists\n\nThese artifacts allow you to step back through the development process and, if there’s a problem, better determine what went wrong and how to address it.\n\n**Recommendation:** Store these artifacts in your source control system for easy reference and to track changes as they’re made.\n\n### Product requirements documents (PRDs)\n\nA product requirements document[^1] tells you *what* you're building and *why* you're building it without digging into *how* it will be built. In traditional software engineering, a product manager conducts research to discover what use cases need to be addressed by a feature or product. This may involve user studies, interviews, market research, or other fact-finding processes. The product manager then synthesizes the data into a set of requirements to address the findings and presents that information to the software engineering manager or lead for review and implementation.\n\nPRD formats vary from organization to organization, but they generally contain this type of information:\n\n* **Background** \\- Contains necessary context to understand what the PRD is describing. This may be a problem statement or an explanation of a use case to be addressed. \n* **Goals** \\- What the requirements are meant to address. \n* **Target Audience/Personas** \\- The intended users of the functionality. \n* **Functional Requirements** \\- Describes what the changes do. \n* **User Stories** \\- Describes what a given user or persona experiences when using this functionality. (For example, “As a user, I want to see my task list when I log in.”) \n* **Constraints** \\- Factors that limit the solution space or otherwise constrain what can be accomplished with this PRD. \n* **Success Metrics** \\- The measurable data indicating that the goals have been achieved.\n\nYou can review the PRD at any point to ensure that the technical design and implementation are proceeding correctly. This is especially helpful when you’re deep into implementation and there’s disagreement on whether the functionality works as intended.\n\nUse AI to:\n\n* Create the PRD from a feature or product description \n* Review the PRD for inconsistencies or ambiguities \n* Ensure alignment of goals and features\n\nIn AI-assisted programming, the PRD is a key input the AI uses to develop a technical design. If there are errors in the PRD, then the ensuing technical design will also contain errors, so it’s important to review a PRD thoroughly to catch any problems. It can be helpful to use one AI to write the PRD and another to review it for inconsistencies or ambiguities.\n\n## Architectural decision records (ADRs)\n\nAn architectural decision record[^2] explains *why* a technical choice was made. While the word “architectural” is in the name, ADRs don’t need to be tied specifically to architectural decisions. Any given project has the potential to yield a number of important technical decisions, such as:\n\n* Do we use a SQL or NoSQL database? \n* Which cloud infrastructure provider do we use? \n* Which framework do we use? \n* What programming language do we use for APIs?\n\nThese decisions are made by humans and likely will remain the domain of humans for quite some time, as these choices often depend on business context to be made correctly.\n\nAn ADR typically has the following sections:\n\n* **Title** \\- A brief description of the decision. \n* **Status** \\- Whether the decision is pending, approved, deprecated, or superseded. \n* **Context** \\- Any relevant background information about the decision, including references to other artifacts. \n* **Decision** \\- The decision that was made. \n* **Consequences** \\- Both the positive and negative consequences of the decision. \n* **Alternatives Considered** \\- Any other options and the reasons for rejection.\n\nADRs are especially beneficial because they remain immutable. The reason why a decision was made doesn’t change. Even as PRDs and TDDs are corrected during implementation to clear up inconsistencies, the ADRs remain as they were. The only potential change is when an ADR status changes (from accepted to deprecated or superseded). \n\nUse AI to:\n\n* Generate a first draft of an ADR based on a decision \n* Propose alternatives during the decision-making process \n* Identify potential consequences \n* Find related ADRs\n\nNot all features require ADRs, especially when building on top of an existing framework or architecture. However, when a significant technical decision is made, documenting it as an ADR provides additional inputs for generating a good TDD and traceability when reviewing the TDD.\n\n## Technical design documents (TDDs)\n\nA technical design document[^3] describes *how* the functionality described in a PRD is implemented. In some companies, this is called an architectural design document or technical specification, but the underlying purpose is the same: to give a high-level overview of the software solution that fulfills the requirements of the PRD. In traditional software engineering, a tech lead or architect is responsible for reviewing a PRD and developing an appropriate technical design. The design is then reviewed by other developers to gather feedback and ensure the scope is correct.\n\nTypical sections in a TDD include:\n\n* **Overview** \\- What the design is meant to cover. \n* **Goals** \\- Specific technical goals to achieve with the design. (As opposed to functional or business goals, which are described in the PRD.) \n* **Background/Context** \\- Any relevant technical information related to the design, such as existing infrastructure or design patterns to be followed. \n* **Requirements** \\- Specific functional (what the system should do) and non-functional (how the system should behave) technical requirements. Non-functional requirements include security, scalability, performance, and reliability. \n* **High-Level Design/Architecture** \\- Describes the technical resources required and how they relate to one another. \n* **Data Design** \\- Any new or existing data sources required. Traditionally, this would involve an entity-relationship diagram. \n* **API Design** \\- The interaction points between existing systems or users and the new design. \n* **Technology Stack** \\- The languages, frameworks, tools, infrastructure, etc., necessary to implement the design. \n* **Security Considerations \\-** Guidelines for how security best practices are followed. \n* **Scalability/Performance** \\- How the system will work under heavy load, including anticipated performance bottlenecks and mitigations. \n* **Testing Strategy** \\- What types of tests (unit, integration, etc.) will be used. \n* **Deployment Plan** \\- How the system will be made available to users. \n* **Monitoring/Observability** \\- How you’ll know if the system is functioning correctly once deployed. \n* **Out of Scope** \\- Anything that’s explicitly not included in the design and won’t be completed as part of this work. This ensures time isn’t wasted by someone (or an AI) inferring a requirement that wasn’t explicitly stated. \n* **Alternatives Considered** \\- Any other approaches that were considered and discarded. This helps answer the question, “Did you think about X?” when it inevitably comes up later.\n\nThe overall purpose of a TDD is to ensure that all the complexities of a software design are taken into account up front, before implementation begins. Catching problems at this stage is significantly cheaper than discovering the same problems during implementation, in which case you often need to undo work.\n\nUse AI to:\n\n* Create the TDD from the PRD and any relevant ADRs. \n* Review the TDD against the PRD to look for inconsistencies, omissions, and errors. \n* Simultaneously update the PRD and TDD to resolve any issues found.\n\nIn AI-assisted programming, the TDD is the last stop before implementation planning, so it’s critical to catch any problems with the technical design here. AI should be able to implement the design using the TDD in conjunction with the PRD and the codebase (IDEs automatically pass the codebase as context to AI). However, it’s often best to generate a task list from the TDD instead of jumping right into implementation.\n\n## Task lists\n\nIn traditional software engineering, the next step after creating a TDD is for the tech lead, engineering manager, and potentially other engineers to break down the design into a series of tasks. The tasks are then scoped to determine the effort required for each task (and potentially a time estimate) and arranged in sequence to ensure that each task can proceed without being blocked by incomplete tasks. The tasks are then assigned to different engineers on the team for implementation.\n\nFor AI-assisted programming, it’s helpful to add even more context than a human would need to complete a task. For human programming, tasks frequently contain a small amount of information and then refer back to the TDD. For AI implementation, each task should contain:\n\n* **Overview/Description** \\- The purpose of this task. \n* **Deliverable** \\- The expected output of the task. \n* **Dependencies** \\- How it relates to other tasks. \n* **Acceptance Criteria** \\- How to verify that the task is complete and working as expected. \n* **References** \\- Specific sections in the PRD and TDD that this task addresses. \n* **Out of Scope** \\- Anything you specifically don’t want completed as part of this task. \n* **Tips** \\- Anything additional that will help a human or AI implement the task (libraries to use, existing code to reuse, resources needed, etc.).\n\nUse AI to:\n\n* Convert a TDD into a list of tasks. \n* Estimate the relative effort associated with each task. \n* Create issues or tickets in your task management software for each task. \n* Verify that the task list completely implements the TDD.\n\nIn AI-assisted programming, generating a task list from the TDD makes it easier to:\n\n1. Validate that the entire TDD is represented in the tasks. \n2. Catch gaps or ambiguities in the TDD. \n3. Use AI to implement one task at a time to reduce context size and verify task completion. \n4. Pause and resume work as necessary. \n5. Iterate on individual tasks when the output isn’t as expected. \n6. Track implementation progress, especially across multiple days or sessions.\n\n## Example: “Save for later” feature\n\nA “save for later” feature was implemented by AI as part of an online shopping cart. Users are complaining that the items they save are disappearing soon after they’re added, often within one day. There seems to be some confusion on the team, as everyone agrees this isn’t the desired behavior.\n\nThe investigation starts by looking at the PRD, which states the following:\n\n* **Requirement**: Users should be able to save items for later and access them anytime they return to the site. \n* **Success metric**: Increase conversion rate by letting users defer purchase decisions. \n* **User story**: As a shopper, I want to save items so I can think about purchases without losing track of products I'm interested in.\n\nThe PRD clearly states that saved items should be accessible “anytime they return to the site.” That means the data is meant to persist and the implementation is out of alignment with the PRD. The next step is to review the TDD.\n\nThe TDD references two ADRs:\n\n* The *Storage for “save for later” items* ADR indicates that PostgreSQL will be used to store the data. PostgreSQL is a persistent data storage mechanism, so we know the data isn’t missing, just unavailable. \n* The *Caching for “save for later” items* ADR indicates that Redis will be used as an in-memory cache for “save for later” items to speed up UI rendering.\n\nFurther down in the TDD:\n\n* **Data design:** Saved items are stored in PostgreSQL `saved_items` table and Redis with key pattern `saved:{user_id}`. \n* **Implementation details:** \n * Default Redis TTL: 86400 seconds (24 hours) to prevent unbounded growth. \n * `POST /saved_items` endpoint writes to both PostgreSQL and Redis. \n * `GET /saved_items` endpoint reads from Redis for better performance.\n\nWhile each piece of the TDD is technically correct, there’s a key missing detail: the `GET /saved_items` endpoint needs to implement a read-through cache so if the data doesn’t exist in Redis it will be fetched from PostgreSQL and then repopulate the cache. Users are seeing their saved items disappear not because they’re being deleted, but because the Redis cache is empty and the entrypoint then didn’t fetch the data from PostgreSQL. \n \nAI missed this crucial detail when generating the TDD. In all likelihood, human reviewers didn’t catch the omission because a read-through cache was implied by the surrounding details. When AI generated a task list from the TDD, a read-through cache was never explicitly planned for or implemented.\n\nIn this case, the TDD generation needed information in addition to the PRD and ADRs to generate the correct design. The team can update the prompt used for this portion of the development process to reduce the likelihood of a similar error of omission in the future. For example, a document describing how the team typically uses read-through caches for PostgreSQL and Redis can be added to the context of TDD generation.\n\nWithout the artifacts to review, it would be difficult to track down the source of the error and prevent similar errors in the future.\n\n## Conclusion\n\nAI-assisted programming offers tremendous potential to accelerate software development, but it requires a fundamental shift in how we approach the development process. The \"vibe coding\" approach that works for quick prototypes becomes a liability in professional settings where maintainability, traceability, and long-term success matter. Unlike human developers who remember why decisions were made, AI has no memory beyond its current context window, making comprehensive documentation essential rather than optional.\n\nBy creating and maintaining proper artifacts (such as PRDs, ADRs, TDDs, and task lists), you build a knowledge foundation that compensates for AI's lack of memory. These artifacts serve dual purposes: they guide AI toward better implementations during development and provide the investigative trail you need when problems occur. When your server goes down at 3 a.m., these artifacts let you quickly trace the issue back to its source, whether that's an ambiguous requirement, a flawed technical decision, or a gap in the implementation. They transform AI from an unpredictable code generator into a reliable development partner.\n\nThe investment in documentation may seem like it slows down initial development, but it pays dividends when you need to debug problems, onboard new team members, or understand decisions made months or years ago. In a world where AI is increasingly involved in writing code, the artifacts you create become even more valuable than the code itself. You'll likely find that the process not only improves your AI-generated code but also clarifies your own thinking about the problem you're solving. Start with your next feature and experience the difference proper artifacts make.\n\n[^1]: [Product requirements](https://www.atlassian.com/agile/product-management/requirements)\n[^2]: [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)\n[^3]: [Technical Design Document Template](https://www.chatprd.ai/templates/technical-design-document-template)\n","content_html":"<p>Much of the hype around AI-assisted programming focuses on “vibe coding,” which means working prompt by prompt to build an application without worrying too much about the generated code. As long as something works, that’s all that matters. While this approach works well for personal and hobby projects, it’s impractical for professional software engineering</p>\n<p>Professional software engineering involves a team of developers working on a shared codebase that’s maintained over time. This creates concerns that go beyond whether the code is working. Significant changes need to be documented to provide traceability when something goes wrong. <em>Traceability</em> is the ability to look through changes and track them back to their root cause, whether that’s a bug fix, a requirements change, or a new feature. Understanding why a change was made, especially one that caused a problem, is essential for maintaining an application over time. That’s why professional software organizations prioritize creating artifacts as the application evolves.</p>\n<h2 id="what-are-artifacts">What are artifacts?</h2>\n<p>An <em>artifact</em> is any output that’s created, used, or modified during the software development process. Issues and pull requests are artifacts, as are diagrams, documents, mockups, and the code itself. Most software teams generate a large number of artifacts, which represent an important part of the process. When something goes wrong, artifacts provide traceability to help determine the origin of the problem.</p>\n<p>When I was learning software development in college, the focus was on front-loading document artifacts to ensure you knew what you were building. We had to create a functional requirements document (FRD, now often called a product requirements document or PRD) describing what the project or feature would do. Then we had to create a technical specification describing the overall design of the code changes. Only once these two documents were complete could we write any code. This is called the <em>waterfall approach</em>, where each stage must be completed before the next can begin.</p>\n<p>With agile methodologies becoming more popular, many teams saw this as license to forego the PRDs and tech specs, and instead “just start coding.” The focus on iterative development, where software is never truly “complete,” meant that these document artifacts took precious time away from the development process. Many teams convinced themselves that two-sentence issue summaries and face-to-face discussions with product managers were enough to implement good software. Documents like PRDs and tech specs became rare in technology companies (outside of high-level architecture and infrastructure discussions, which often had extensive specifications and diagrams). The argument was that if you had a question about why something was done a particular way, you could just ask the person who did it.</p>\n<h2 id="your-ai-teammates-forgetfulness">Your AI teammate’s forgetfulness</h2>\n<p>When AI-assisted programming began, developers quickly realized that the models didn’t always produce reliable results. Far from deterministic, the models may produce wildly different output when prompts aren’t specific enough. AI-powered IDEs do their best to provide additional context to the models to make output more reliable, yet developers continue to find that longer prompts produce better results.</p>\n<p>Here’s the problem: Your AI pair programmer has a very short memory. It can’t tell you why it made a decision six months ago that brought down your server today. Human programmers are both implementers and stores of knowledge, while AI is only an implementer. The model doesn’t provide traceability beyond the scope of its current context window. If you “vibe coded” an implementation and your server goes down, there’s no way to tell why. Did the model generate insecure code that left the server vulnerable to attack? If so, why? Did it not know the code had to be secure? Was it something in the original prompt that led it to believe the code didn’t need to be secure? There’s no way to know what part of the process broke down, which means additional time spent before the problem can be addressed and a higher likelihood of a similar problem in the future.</p>\n<p>With the proper artifacts available, however, the investigation proceeds quickly and systematically. Because some artifacts are used directly as prompts, it’s much easier to discover where an ambiguity might have led a model to make an incorrect decision. The type of artifacts you use and the level of detail in each are important for this process.</p>\n<h2 id="artifacts-for-ai-assisted-programming">Artifacts for AI-assisted programming</h2>\n<p>While there are many different artifacts that can be useful for AI-assisted programming, I’ve found the following to be among the most important:</p>\n<ul>\n<li>Product requirements documents (PRDs)</li>\n<li>Architectural decision records (ADRs)</li>\n<li>Technical design documents (TDDs)</li>\n<li>Task lists</li>\n</ul>\n<p>These artifacts allow you to step back through the development process and, if there’s a problem, better determine what went wrong and how to address it.</p>\n<p><strong>Recommendation:</strong> Store these artifacts in your source control system for easy reference and to track changes as they’re made.</p>\n<h3 id="product-requirements-documents-prds">Product requirements documents (PRDs)</h3>\n<p>A product requirements document<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> tells you <em>what</em> you’re building and <em>why</em> you’re building it without digging into <em>how</em> it will be built. In traditional software engineering, a product manager conducts research to discover what use cases need to be addressed by a feature or product. This may involve user studies, interviews, market research, or other fact-finding processes. The product manager then synthesizes the data into a set of requirements to address the findings and presents that information to the software engineering manager or lead for review and implementation.</p>\n<p>PRD formats vary from organization to organization, but they generally contain this type of information:</p>\n<ul>\n<li><strong>Background</strong> - Contains necessary context to understand what the PRD is describing. This may be a problem statement or an explanation of a use case to be addressed.</li>\n<li><strong>Goals</strong> - What the requirements are meant to address.</li>\n<li><strong>Target Audience/Personas</strong> - The intended users of the functionality.</li>\n<li><strong>Functional Requirements</strong> - Describes what the changes do.</li>\n<li><strong>User Stories</strong> - Describes what a given user or persona experiences when using this functionality. (For example, “As a user, I want to see my task list when I log in.”)</li>\n<li><strong>Constraints</strong> - Factors that limit the solution space or otherwise constrain what can be accomplished with this PRD.</li>\n<li><strong>Success Metrics</strong> - The measurable data indicating that the goals have been achieved.</li>\n</ul>\n<p>You can review the PRD at any point to ensure that the technical design and implementation are proceeding correctly. This is especially helpful when you’re deep into implementation and there’s disagreement on whether the functionality works as intended.</p>\n<p>Use AI to:</p>\n<ul>\n<li>Create the PRD from a feature or product description</li>\n<li>Review the PRD for inconsistencies or ambiguities</li>\n<li>Ensure alignment of goals and features</li>\n</ul>\n<p>In AI-assisted programming, the PRD is a key input the AI uses to develop a technical design. If there are errors in the PRD, then the ensuing technical design will also contain errors, so it’s important to review a PRD thoroughly to catch any problems. It can be helpful to use one AI to write the PRD and another to review it for inconsistencies or ambiguities.</p>\n<h2 id="architectural-decision-records-adrs">Architectural decision records (ADRs)</h2>\n<p>An architectural decision record<sup><a href="#user-content-fn-2" id="user-content-fnref-2" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup> explains <em>why</em> a technical choice was made. While the word “architectural” is in the name, ADRs don’t need to be tied specifically to architectural decisions. Any given project has the potential to yield a number of important technical decisions, such as:</p>\n<ul>\n<li>Do we use a SQL or NoSQL database?</li>\n<li>Which cloud infrastructure provider do we use?</li>\n<li>Which framework do we use?</li>\n<li>What programming language do we use for APIs?</li>\n</ul>\n<p>These decisions are made by humans and likely will remain the domain of humans for quite some time, as these choices often depend on business context to be made correctly.</p>\n<p>An ADR typically has the following sections:</p>\n<ul>\n<li><strong>Title</strong> - A brief description of the decision.</li>\n<li><strong>Status</strong> - Whether the decision is pending, approved, deprecated, or superseded.</li>\n<li><strong>Context</strong> - Any relevant background information about the decision, including references to other artifacts.</li>\n<li><strong>Decision</strong> - The decision that was made.</li>\n<li><strong>Consequences</strong> - Both the positive and negative consequences of the decision.</li>\n<li><strong>Alternatives Considered</strong> - Any other options and the reasons for rejection.</li>\n</ul>\n<p>ADRs are especially beneficial because they remain immutable. The reason why a decision was made doesn’t change. Even as PRDs and TDDs are corrected during implementation to clear up inconsistencies, the ADRs remain as they were. The only potential change is when an ADR status changes (from accepted to deprecated or superseded).</p>\n<p>Use AI to:</p>\n<ul>\n<li>Generate a first draft of an ADR based on a decision</li>\n<li>Propose alternatives during the decision-making process</li>\n<li>Identify potential consequences</li>\n<li>Find related ADRs</li>\n</ul>\n<p>Not all features require ADRs, especially when building on top of an existing framework or architecture. However, when a significant technical decision is made, documenting it as an ADR provides additional inputs for generating a good TDD and traceability when reviewing the TDD.</p>\n<h2 id="technical-design-documents-tdds">Technical design documents (TDDs)</h2>\n<p>A technical design document<sup><a href="#user-content-fn-3" id="user-content-fnref-3" data-footnote-ref="" aria-describedby="footnote-label">3</a></sup> describes <em>how</em> the functionality described in a PRD is implemented. In some companies, this is called an architectural design document or technical specification, but the underlying purpose is the same: to give a high-level overview of the software solution that fulfills the requirements of the PRD. In traditional software engineering, a tech lead or architect is responsible for reviewing a PRD and developing an appropriate technical design. The design is then reviewed by other developers to gather feedback and ensure the scope is correct.</p>\n<p>Typical sections in a TDD include:</p>\n<ul>\n<li><strong>Overview</strong> - What the design is meant to cover.</li>\n<li><strong>Goals</strong> - Specific technical goals to achieve with the design. (As opposed to functional or business goals, which are described in the PRD.)</li>\n<li><strong>Background/Context</strong> - Any relevant technical information related to the design, such as existing infrastructure or design patterns to be followed.</li>\n<li><strong>Requirements</strong> - Specific functional (what the system should do) and non-functional (how the system should behave) technical requirements. Non-functional requirements include security, scalability, performance, and reliability.</li>\n<li><strong>High-Level Design/Architecture</strong> - Describes the technical resources required and how they relate to one another.</li>\n<li><strong>Data Design</strong> - Any new or existing data sources required. Traditionally, this would involve an entity-relationship diagram.</li>\n<li><strong>API Design</strong> - The interaction points between existing systems or users and the new design.</li>\n<li><strong>Technology Stack</strong> - The languages, frameworks, tools, infrastructure, etc., necessary to implement the design.</li>\n<li><strong>Security Considerations -</strong> Guidelines for how security best practices are followed.</li>\n<li><strong>Scalability/Performance</strong> - How the system will work under heavy load, including anticipated performance bottlenecks and mitigations.</li>\n<li><strong>Testing Strategy</strong> - What types of tests (unit, integration, etc.) will be used.</li>\n<li><strong>Deployment Plan</strong> - How the system will be made available to users.</li>\n<li><strong>Monitoring/Observability</strong> - How you’ll know if the system is functioning correctly once deployed.</li>\n<li><strong>Out of Scope</strong> - Anything that’s explicitly not included in the design and won’t be completed as part of this work. This ensures time isn’t wasted by someone (or an AI) inferring a requirement that wasn’t explicitly stated.</li>\n<li><strong>Alternatives Considered</strong> - Any other approaches that were considered and discarded. This helps answer the question, “Did you think about X?” when it inevitably comes up later.</li>\n</ul>\n<p>The overall purpose of a TDD is to ensure that all the complexities of a software design are taken into account up front, before implementation begins. Catching problems at this stage is significantly cheaper than discovering the same problems during implementation, in which case you often need to undo work.</p>\n<p>Use AI to:</p>\n<ul>\n<li>Create the TDD from the PRD and any relevant ADRs.</li>\n<li>Review the TDD against the PRD to look for inconsistencies, omissions, and errors.</li>\n<li>Simultaneously update the PRD and TDD to resolve any issues found.</li>\n</ul>\n<p>In AI-assisted programming, the TDD is the last stop before implementation planning, so it’s critical to catch any problems with the technical design here. AI should be able to implement the design using the TDD in conjunction with the PRD and the codebase (IDEs automatically pass the codebase as context to AI). However, it’s often best to generate a task list from the TDD instead of jumping right into implementation.</p>\n<h2 id="task-lists">Task lists</h2>\n<p>In traditional software engineering, the next step after creating a TDD is for the tech lead, engineering manager, and potentially other engineers to break down the design into a series of tasks. The tasks are then scoped to determine the effort required for each task (and potentially a time estimate) and arranged in sequence to ensure that each task can proceed without being blocked by incomplete tasks. The tasks are then assigned to different engineers on the team for implementation.</p>\n<p>For AI-assisted programming, it’s helpful to add even more context than a human would need to complete a task. For human programming, tasks frequently contain a small amount of information and then refer back to the TDD. For AI implementation, each task should contain:</p>\n<ul>\n<li><strong>Overview/Description</strong> - The purpose of this task.</li>\n<li><strong>Deliverable</strong> - The expected output of the task.</li>\n<li><strong>Dependencies</strong> - How it relates to other tasks.</li>\n<li><strong>Acceptance Criteria</strong> - How to verify that the task is complete and working as expected.</li>\n<li><strong>References</strong> - Specific sections in the PRD and TDD that this task addresses.</li>\n<li><strong>Out of Scope</strong> - Anything you specifically don’t want completed as part of this task.</li>\n<li><strong>Tips</strong> - Anything additional that will help a human or AI implement the task (libraries to use, existing code to reuse, resources needed, etc.).</li>\n</ul>\n<p>Use AI to:</p>\n<ul>\n<li>Convert a TDD into a list of tasks.</li>\n<li>Estimate the relative effort associated with each task.</li>\n<li>Create issues or tickets in your task management software for each task.</li>\n<li>Verify that the task list completely implements the TDD.</li>\n</ul>\n<p>In AI-assisted programming, generating a task list from the TDD makes it easier to:</p>\n<ol>\n<li>Validate that the entire TDD is represented in the tasks.</li>\n<li>Catch gaps or ambiguities in the TDD.</li>\n<li>Use AI to implement one task at a time to reduce context size and verify task completion.</li>\n<li>Pause and resume work as necessary.</li>\n<li>Iterate on individual tasks when the output isn’t as expected.</li>\n<li>Track implementation progress, especially across multiple days or sessions.</li>\n</ol>\n<h2 id="example-save-for-later-feature">Example: “Save for later” feature</h2>\n<p>A “save for later” feature was implemented by AI as part of an online shopping cart. Users are complaining that the items they save are disappearing soon after they’re added, often within one day. There seems to be some confusion on the team, as everyone agrees this isn’t the desired behavior.</p>\n<p>The investigation starts by looking at the PRD, which states the following:</p>\n<ul>\n<li><strong>Requirement</strong>: Users should be able to save items for later and access them anytime they return to the site.</li>\n<li><strong>Success metric</strong>: Increase conversion rate by letting users defer purchase decisions.</li>\n<li><strong>User story</strong>: As a shopper, I want to save items so I can think about purchases without losing track of products I’m interested in.</li>\n</ul>\n<p>The PRD clearly states that saved items should be accessible “anytime they return to the site.” That means the data is meant to persist and the implementation is out of alignment with the PRD. The next step is to review the TDD.</p>\n<p>The TDD references two ADRs:</p>\n<ul>\n<li>The <em>Storage for “save for later” items</em> ADR indicates that PostgreSQL will be used to store the data. PostgreSQL is a persistent data storage mechanism, so we know the data isn’t missing, just unavailable.</li>\n<li>The <em>Caching for “save for later” items</em> ADR indicates that Redis will be used as an in-memory cache for “save for later” items to speed up UI rendering.</li>\n</ul>\n<p>Further down in the TDD:</p>\n<ul>\n<li><strong>Data design:</strong> Saved items are stored in PostgreSQL <code>saved_items</code> table and Redis with key pattern <code>saved:{user_id}</code>.</li>\n<li><strong>Implementation details:</strong>\n<ul>\n<li>Default Redis TTL: 86400 seconds (24 hours) to prevent unbounded growth.</li>\n<li><code>POST /saved_items</code> endpoint writes to both PostgreSQL and Redis.</li>\n<li><code>GET /saved_items</code> endpoint reads from Redis for better performance.</li>\n</ul>\n</li>\n</ul>\n<p>While each piece of the TDD is technically correct, there’s a key missing detail: the <code>GET /saved_items</code> endpoint needs to implement a read-through cache so if the data doesn’t exist in Redis it will be fetched from PostgreSQL and then repopulate the cache. Users are seeing their saved items disappear not because they’re being deleted, but because the Redis cache is empty and the entrypoint then didn’t fetch the data from PostgreSQL.</p>\n<p>AI missed this crucial detail when generating the TDD. In all likelihood, human reviewers didn’t catch the omission because a read-through cache was implied by the surrounding details. When AI generated a task list from the TDD, a read-through cache was never explicitly planned for or implemented.</p>\n<p>In this case, the TDD generation needed information in addition to the PRD and ADRs to generate the correct design. The team can update the prompt used for this portion of the development process to reduce the likelihood of a similar error of omission in the future. For example, a document describing how the team typically uses read-through caches for PostgreSQL and Redis can be added to the context of TDD generation.</p>\n<p>Without the artifacts to review, it would be difficult to track down the source of the error and prevent similar errors in the future.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>AI-assisted programming offers tremendous potential to accelerate software development, but it requires a fundamental shift in how we approach the development process. The “vibe coding” approach that works for quick prototypes becomes a liability in professional settings where maintainability, traceability, and long-term success matter. Unlike human developers who remember why decisions were made, AI has no memory beyond its current context window, making comprehensive documentation essential rather than optional.</p>\n<p>By creating and maintaining proper artifacts (such as PRDs, ADRs, TDDs, and task lists), you build a knowledge foundation that compensates for AI’s lack of memory. These artifacts serve dual purposes: they guide AI toward better implementations during development and provide the investigative trail you need when problems occur. When your server goes down at 3 a.m., these artifacts let you quickly trace the issue back to its source, whether that’s an ambiguous requirement, a flawed technical decision, or a gap in the implementation. They transform AI from an unpredictable code generator into a reliable development partner.</p>\n<p>The investment in documentation may seem like it slows down initial development, but it pays dividends when you need to debug problems, onboard new team members, or understand decisions made months or years ago. In a world where AI is increasingly involved in writing code, the artifacts you create become even more valuable than the code itself. You’ll likely find that the process not only improves your AI-generated code but also clarifies your own thinking about the problem you’re solving. Start with your next feature and experience the difference proper artifacts make.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-1">\n<p><a href="https://www.atlassian.com/agile/product-management/requirements">Product requirements</a> <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-2">\n<p><a href="https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions">Documenting Architecture Decisions</a> <a href="#user-content-fnref-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-3">\n<p><a href="https://www.chatprd.ai/templates/technical-design-document-template">Technical Design Document Template</a> <a href="#user-content-fnref-3" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n</ol>\n</section>","tags":["AI","Specifications","PRDs","ADRs","Artifacts"],"date_published":"2026-02-03T00:00:00.000Z","date_updated":"2026-02-03T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2026/01/coder-orchestrator-future-software-engineering/","url":"https://humanwhocodes.com/blog/2026/01/coder-orchestrator-future-software-engineering/","title":"From Coder to Orchestrator: The future of software engineering with AI","author":{"name":"Nicholas C. Zakas"},"summary":"The software engineering job of the future won't involve writing code; it will involve orchestrating AI agents to write code for you.","content_text":"\nThe software engineering industry is undergoing a major AI-driven transition in how we work. The days when humans needed to write every line of code are already behind us as LLMs become more capable and reliable. The improvement in code output during 2025 alone has been astounding. I've personally watched LLMs struggle with certain problems, then a few months later, solve them completely and efficiently. Progress will likely accelerate even further in 2026\\.\n\nAs Addy Osmani put it, we’re moving from coder to conductor to orchestrator[^1].\n\n## From autocomplete to agent-based development\n\nAt the start of 2024, AI-assisted programming resembled a significantly improved autocomplete. You could maximize AI's value by having it write tedious, common patterns learned from its training data. Coders had a form of \"cruise control\"—models filled in the blanks as you worked, but you remained the driver of the development process. The time savings came primarily from mundane tasks like writing documentation comments, utility functions, data models, and tests.\n\nIn 2025, we got our first taste of partially autonomous models that could take a single prompt and figure out how to implement the request. The coder now acted more like a *conductor*, giving an LLM instructions to complete a task, then sitting back to see what it produced, providing feedback, and repeating the cycle. Models became capable of creating complex, multi-file solutions, and in some cases, complete applications, from a single prompt. While we still initiated the code creation process, we acted like an orchestra conductor guiding the violin section through a carefully measured motif. We remained ultimately responsible for the output but spent more time reviewing than coding. We'd been upgraded from cruise control to partially self-driving.\n\nTowards the end of 2025, fully autonomous background agents gave rise to a new way of working. Instead of limiting ourselves to one synchronous AI session at a time, we can now act as an *orchestrator*, arranging work across multiple agents and determining how to combine them later. Through offerings like Cursor cloud agents[^2] and GitHub Copilot coding agent[^3], you can give instructions to be completed without active monitoring. These cloud-based agents continue executing until the task is complete, then notify you when it's time to review their work. The isolated cloud environments remove much of the security risk of running agents on personal computers, allowing them to try, fail, and retry approaches without risking collateral damage.\n\nThis human-as-orchestrator trend appears to be the future of software development, making it worth exploring how the human development experience will change in the coming years.\n\n## From text-focused IDEs to task-focused IDEs\n\nWith humans no longer responsible for writing code, the question arises: what will the integrated development environment (IDE) interface look like? Undoubtedly, humans will still initiate code generation, so what kind of interface will that require?\n\nIf humans are primarily orchestrators, then IDEs will evolve to focus on managing coding agents instead of editing code. We can see this evolution already happening with GitHub Mission Control[^4] on the web and Visual Studio Code agents panel[^5] and Google Antigravity[^6] on the desktop.\n\nBoth interfaces put agent management front and center, pushing code into the background. The user experience is optimized for quickly scanning agent sessions to see which are pending, complete, or stuck and need intervention. You can also easily switch between different sessions, each represented by a chat interface that allows you to interact and iterate with them all in one place.\n\nIn the future, I expect these agent-focused interfaces to evolve to provide ways to combine outputs from different agent sessions into a finished project. I can imagine an IDE that manages creation of the front end, back end, and data layer of an application in separate sessions, then easily incorporates all three into a single, functional codebase.\n\nI think we could see this evolution move quickly, with most IDEs in 2028 being primarily agent-focused.\n\n## From hands-on coding to no-hands-on coding\n\nIf agents are primarily responsible for coding, it's not a stretch to think that at some point, humans may not be allowed to code by hand at work. After all, once AI can code better than humans, why would you want a human to touch the code? Doing so would introduce unnecessary risk and increase the potential for bugs.\n\nThink of this as similar to self-driving cars. Once self-driving cars become established and ubiquitous, human driving will be considered dangerous and unpredictable. Insurance rates for human drivers will likely skyrocket due to the risk compared to the alternative. While driving competitions probably won't go away, public streets will be dominated by self-driving cars, nearly guaranteeing safe, traffic-free passage anywhere you want to go. Certain roads may even ban human drivers due to the inefficiencies and associated danger.\n\nCoding will face a similar shift, especially in high-risk systems such as self-driving, medical, and financial. It will be deemed \"too important\" to leave in human hands. Just as no Fortune 500 company would consider doing its bookkeeping by hand, the idea of leaving such important functionality to fallible humans will seem laughable at best and irresponsible at worst.\n\nInsurance companies will likely force this transition through higher business insurance rates for companies that allow humans to code. Policies already require certain business practices, such as daily backups, to get coverage. These policies are constantly updated to include technical best practices, and at some point, it will be a best practice to ensure no human makes direct edits to source code. All edits must be done through an AI that constantly checks for errors and security problems simultaneously.\n\nThis transition is likely to take more time, but I’d bet that we start seeing the first glimpses of this approach as we approach 2030\\.\n\n## From code reviewer to task verifier\n\nAs I'm writing this, AI is already capable of writing both source code and unit tests for that code. When integration tests already exist, AI is also capable of adding and modifying them. Right now, I haven't experienced AI being able to set up a full integration test environment on its own, though I suspect this will change relatively quickly. The important human value added to the process is reviewing the code to ensure it meets requirements and follows associated best practices. At this stage, the source code serves primarily as a human auditing tool.\n\nOnce AI is better than humans at writing code, it will also be better at reviewing code. Reviewing code is a bit more complex than writing it because you (or a model) need the correct context to understand the code. Nevertheless, AI will eventually meet this bar, and at that point, humans will no longer need to review the generated code. Through a series of non-deterministic and deterministic analysis, AI will identify any problems in the code and fix them automatically.\n\nIn all likelihood, this will become part of the development process where one agent generates the code and another agent reviews it and provides feedback. The first agent then makes changes to address the feedback, triggering another review. The process continues until the code is deemed acceptable. Google Antigravity already implements something along these lines by having the agent generate and execute a verification plan[^7] after code generation is complete.\n\nWhen the agents agree on the state of the code, the human's job is reduced to verifying that the requested task is completed as specified. Even this step will rely more on artifacts generated by the agents rather than on reviewing code. For instance, instead of conducting a code review to determine that a button to create a new task was added, an agent will provide screenshots of the relevant new UI and a video showing the new interactions. If there are any problems, the human provides feedback and the coding agent makes the appropriate changes. Google Antigravity has already started down this path by taking screenshots and videos[^8] of UI changes.\n\nThe change will be automatically deployed after the human reviewer verifies the task is complete.\n\nGiven that this is the way Google Antigravity currently works, I expect this approach to be common in 2028 and the norm by 2030\\.\n\n## Future programming languages\n\n“Programs must be written for people to read, and only incidentally for machines to execute.” \n― Harold Abelson, Structure and Interpretation of Computer Programs \n\nWhile AI currently uses existing programming languages, I don't think that will necessarily remain the case. The current generation of higher-level languages was created to make programming easier for humans compared to manually executing processor instructions. In a world where humans don't need to write or review code, the utility of these languages is significantly lessened, especially considering the extra tokens necessary to create visually appealing patterns for humans to recognize.\n\nMore token-efficient programming languages can certainly be created, allowing AI to generate the same code using fewer resources. We already have Token-Oriented Object Notation[^9] (TOON) as a more token-efficient alternative to JSON for use with LLMs. I don't think new imperative languages are far off. Given the amount of AI-generated code we already have, and how much that will increase in the future, creating languages with more compact syntax could both increase the speed of code generation and reduce the cost.\n\nA common pushback to this point is that AI is only good at coding because it was trained on a massive amount of code spanning decades. That code represents both best practices and common patterns to be mimicked in generated code. While that's true of today's LLMs, I don't think we should assume that all future models will need the same amount of training or sample data to produce functionally equivalent code in a new programming language. LLMs may not end up being the code generation model of choice as AI continues to evolve and new model types are created. It's possible we'll end up with a model that can write excellent code simply by reviewing the language specification and discovering best practices along the way.\n\nIn the end, code will be written primarily for computers to execute and only incidentally for humans to read. A full transition to this approach may take until 2035 to have compilers and interpreters for new languages replace existing ones. However, new languages could be developed in the meantime to act as intermediate languages to be transpiled into their final form by deterministic tools.\n\n## From engineering teams to minimum viable engineering teams (MVET)\n\nIn the new orchestrator role, a single engineer will guide multiple agents producing code equivalent to multiple engineers. The result will necessarily be smaller engineering teams with the bare minimum number of engineers to get the desired output. I call this a minimum viable engineering team (MVET). How small the MVET will be is based primarily on non-technical factors, such as:\n\n* **Will a single engineer working in isolation be happy and dedicated?** While many engineers claim they wish they could just do all the work themselves without dealing with the messiness of other humans, that might not be the reality. Humans are social creatures, and part of the fun is collaborating with others to solve interesting problems. There may be some minimum team size that's optimal for productive engineers. \n* **What value do companies place on eliminating single points of failure (SPOFs)?** It may be tempting to have a single engineer, especially at a small company or startup, but what if that engineer goes on vacation, gets sick, or leaves? Or, knowing their worth, leverages their position for more pay or other concessions? It may be worth the extra payroll to have redundancy on the engineering team to eliminate this SPOF. \n* **How important are subject matter experts?** Will companies want to hire specialists or generalists? In a complex system, expecting one person to be an expert in all aspects of an application is unrealistic. Companies may still want a front-end expert, a back-end expert, and a database expert to orchestrate the agents associated with those areas. \n* **What kind of a talent pipeline does the company want?** Companies will want some continuity plan for when engineers leave. Having at least one senior and one junior engineer on a task both eliminates a SPOF while planning for a future in which the senior engineer leaves. \n* **Does AI orchestration productivity increase with more engineers?** We may discover that engineers are more effective orchestrators when they have other engineers to collaborate with. Traditional pair programming techniques such as driver-navigator[^10] may reduce errors and produce higher-quality output. Even without following any strict collaboration setup, just having someone else to bounce ideas off of and provide a different perspective may yield better results. In that case, it would benefit the company to have at least two engineers per orchestration.\n\nThere will undoubtedly be companies that try to pare down their engineering teams to the bare minimum. My hypothesis is that these companies will suffer as a result and eventually realize that an MVET is never just one person.\n\nEngineering teams will be smaller in the future, but how much smaller will vary by company. I've worked at many companies that overhired engineers because they were focused on the desired lines of code or parallelization necessary for a given project. With so much code needed, it was easy for subpar coders to find and keep well-paying jobs even as they underperformed. These individuals will not have software engineering jobs in the future. AI can already produce better quality code at a much lower cost.\n\nWe’ve already seen the transition to smaller teams in 2025, and I think we’ll see a permanent rethinking of engineering team size by 2028\\.\n\n## From delivering code to delivering value\n\nSo who will have software engineering jobs? In the near term, the engineers who keep their jobs will show an aptitude not just for creating code but also for organizing work. These are typically skills people learn as they progress from junior engineer to senior engineer to tech lead and beyond. At that point, the job becomes less about delivering code and more about delivering value.\n\nMany tech leads are initially frustrated that they need to spend less time coding to take on other tasks like reviewing technical specifications and pull requests, mentoring, and assigning tasks. They're frequently forced to start delegating work that they would otherwise prefer to do themselves. Eventually, though, tech leads relax into this role and understand that they can deliver value in many ways, not just through writing code. In fact, they can act as a multiplier on the team and make everyone else more productive.\n\nFuture software engineers will need to behave more like tech leads right from the start of their careers. These are the skills I think will be important going forward:\n\n* **Organization.** Software development using agents means much more work to organize tasks across agents. Engineers will need to develop \"flight plans\" that map out how work will be split, parallelized, and merged to achieve the desired result. This includes logging and observability work to ensure traceability for agent workstreams. \n* **Communication.** With fewer engineers per team, ironically, communication among humans becomes more important. There will be much more cross-functional communication, and miscommunication is more likely to result in wasted work. \n* **Systems thinking.** Engineers will no longer be able to focus on a particular component in a system. Instead, they'll need to think about how pieces fit together into a greater whole. \n* **Model selection.** Just as engineers today need to understand which languages to use for specific types of problems, we'll also need to know which model is best suited for which types of tasks. Even within a particular model family, it's important to know which generation and variant to use. For example, when is it better to use Claude 3.5 Sonnet vs. Claude 4.5 Haiku? \n* **Prompt engineering.** With all the agent interaction, writing prompts is a key skill. Prompts need to be specific enough to ensure agents aren't wasting time misinterpreting commands. Practices like providing examples and counterexamples, using steps and lists, and breaking complex tasks into individual prompts are all important tools for this role. \n* **Output validation.** Much of an engineer's job will be validating AI output. To do so, we will need to create deterministic workflows that can evaluate it. Engineers must have a good sense of when something is incomplete or error-prone before it deploys to production. \n* **Debugging workflows.** When agents don't produce the desired result or the output isn't working correctly, engineers will need to debug workflows to determine the source of the problem. \n* **Agent-focused information management.** Documentation is critical when agents are doing all the work. Information needs to be structured for AI consumption, and retrieval systems need to be available to agents so they can fetch the up-to-date data they need on demand. \n* **Security.** Making sure agents don't access sensitive systems or fall victim to prompt injection attacks or jailbreaking will be a constant concern. Even cloud agents may be able to escape their sandbox, so this must be taken into account. \n* **Budget management.** Engineers may be given an AI budget on a weekly or monthly basis to keep costs in check. Whether that budget comes in the form of dollars, tokens, or credits, understanding the value you'll get from a specific model's output versus the cost to generate it will likely become an important skill.\n\nUp to this point, the ability to create functional code could land you an entry-level job as a software engineer. With code generation now commoditized through AI, this is no longer the case. The skills companies look for are already changing, making it more difficult for bootcamp-taught individuals to attain jobs. The necessary skills are those that are more difficult to teach and often hard-earned through on-the-job experience. As such, software engineering jobs will likely attract fewer people, as the \"fun\" part of the job is now being handled by AI and the more manager-like part of the job becomes more important.\n\nThis transition is already taking place and I expect it to be mostly complete by 2028\\.\n\n## Conclusion\n\nThe transition from coder to orchestrator represents a fundamental shift in how software is created. While the timeline for each phase varies, the direction is clear: humans will spend less time writing code and more time directing AI agents to do so. This isn't a distant future scenario. The tools and practices described here are already emerging, with full adoption of orchestrator-based development likely within the next five years.\n\nThis shift will be disruptive, particularly for those whose primary value proposition is writing code. Entry-level positions will become scarcer, and the barrier to entry will rise as companies seek engineers with organizational and strategic skills typically acquired through years of experience. However, for those who adapt, the role of software engineer will become more creative and strategic, focused on solving problems at a higher level of abstraction.\n\nThe future of software engineering isn't about humans versus AI. It's about humans and AI working together, with humans providing the vision, judgment, and orchestration while AI handles the implementation details. Those who embrace this partnership and develop the skills to thrive in an orchestrator role will find themselves not replaced by AI, but empowered by it.\n\n[^1]: [Conductors to Orchestrators: The Future of Agentic Coding](https://addyo.substack.com/p/conductors-to-orchestrators-the-future)\n[^2]: [Cloud Agents](https://cursor.com/docs/cloud-agent)\n[^3]: [About GitHub Copilot coding agent](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent)\n[^4]: [GitHub Mission Control](https://github.com/copilot/agents)\n[^5]: [Using agents in Visual Studio Code](https://code.visualstudio.com/docs/copilot/agents/overview#_manage-agent-sessions)\n[^6]: [Google Antigravity](https://antigravity.google/)\n[^7]: [Verification Plans in Google Antigravity](https://youtu.be/htV29JrMXmA)\n[^8]: [Frontend - Google Antigravity](https://antigravity.google/use-cases/frontend)\n[^9]: [TOON - Token-Oriented Object Notation](https://toonformat.dev/)\n[^10]: [On Pair Programming](https://martinfowler.com/articles/on-pair-programming.html#Styles)\n","content_html":"<p>The software engineering industry is undergoing a major AI-driven transition in how we work. The days when humans needed to write every line of code are already behind us as LLMs become more capable and reliable. The improvement in code output during 2025 alone has been astounding. I’ve personally watched LLMs struggle with certain problems, then a few months later, solve them completely and efficiently. Progress will likely accelerate even further in 2026.</p>\n<p>As Addy Osmani put it, we’re moving from coder to conductor to orchestrator<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup>.</p>\n<h2 id="from-autocomplete-to-agent-based-development">From autocomplete to agent-based development</h2>\n<p>At the start of 2024, AI-assisted programming resembled a significantly improved autocomplete. You could maximize AI’s value by having it write tedious, common patterns learned from its training data. Coders had a form of “cruise control”—models filled in the blanks as you worked, but you remained the driver of the development process. The time savings came primarily from mundane tasks like writing documentation comments, utility functions, data models, and tests.</p>\n<p>In 2025, we got our first taste of partially autonomous models that could take a single prompt and figure out how to implement the request. The coder now acted more like a <em>conductor</em>, giving an LLM instructions to complete a task, then sitting back to see what it produced, providing feedback, and repeating the cycle. Models became capable of creating complex, multi-file solutions, and in some cases, complete applications, from a single prompt. While we still initiated the code creation process, we acted like an orchestra conductor guiding the violin section through a carefully measured motif. We remained ultimately responsible for the output but spent more time reviewing than coding. We’d been upgraded from cruise control to partially self-driving.</p>\n<p>Towards the end of 2025, fully autonomous background agents gave rise to a new way of working. Instead of limiting ourselves to one synchronous AI session at a time, we can now act as an <em>orchestrator</em>, arranging work across multiple agents and determining how to combine them later. Through offerings like Cursor cloud agents<sup><a href="#user-content-fn-2" id="user-content-fnref-2" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup> and GitHub Copilot coding agent<sup><a href="#user-content-fn-3" id="user-content-fnref-3" data-footnote-ref="" aria-describedby="footnote-label">3</a></sup>, you can give instructions to be completed without active monitoring. These cloud-based agents continue executing until the task is complete, then notify you when it’s time to review their work. The isolated cloud environments remove much of the security risk of running agents on personal computers, allowing them to try, fail, and retry approaches without risking collateral damage.</p>\n<p>This human-as-orchestrator trend appears to be the future of software development, making it worth exploring how the human development experience will change in the coming years.</p>\n<h2 id="from-text-focused-ides-to-task-focused-ides">From text-focused IDEs to task-focused IDEs</h2>\n<p>With humans no longer responsible for writing code, the question arises: what will the integrated development environment (IDE) interface look like? Undoubtedly, humans will still initiate code generation, so what kind of interface will that require?</p>\n<p>If humans are primarily orchestrators, then IDEs will evolve to focus on managing coding agents instead of editing code. We can see this evolution already happening with GitHub Mission Control<sup><a href="#user-content-fn-4" id="user-content-fnref-4" data-footnote-ref="" aria-describedby="footnote-label">4</a></sup> on the web and Visual Studio Code agents panel<sup><a href="#user-content-fn-5" id="user-content-fnref-5" data-footnote-ref="" aria-describedby="footnote-label">5</a></sup> and Google Antigravity<sup><a href="#user-content-fn-6" id="user-content-fnref-6" data-footnote-ref="" aria-describedby="footnote-label">6</a></sup> on the desktop.</p>\n<p>Both interfaces put agent management front and center, pushing code into the background. The user experience is optimized for quickly scanning agent sessions to see which are pending, complete, or stuck and need intervention. You can also easily switch between different sessions, each represented by a chat interface that allows you to interact and iterate with them all in one place.</p>\n<p>In the future, I expect these agent-focused interfaces to evolve to provide ways to combine outputs from different agent sessions into a finished project. I can imagine an IDE that manages creation of the front end, back end, and data layer of an application in separate sessions, then easily incorporates all three into a single, functional codebase.</p>\n<p>I think we could see this evolution move quickly, with most IDEs in 2028 being primarily agent-focused.</p>\n<h2 id="from-hands-on-coding-to-no-hands-on-coding">From hands-on coding to no-hands-on coding</h2>\n<p>If agents are primarily responsible for coding, it’s not a stretch to think that at some point, humans may not be allowed to code by hand at work. After all, once AI can code better than humans, why would you want a human to touch the code? Doing so would introduce unnecessary risk and increase the potential for bugs.</p>\n<p>Think of this as similar to self-driving cars. Once self-driving cars become established and ubiquitous, human driving will be considered dangerous and unpredictable. Insurance rates for human drivers will likely skyrocket due to the risk compared to the alternative. While driving competitions probably won’t go away, public streets will be dominated by self-driving cars, nearly guaranteeing safe, traffic-free passage anywhere you want to go. Certain roads may even ban human drivers due to the inefficiencies and associated danger.</p>\n<p>Coding will face a similar shift, especially in high-risk systems such as self-driving, medical, and financial. It will be deemed “too important” to leave in human hands. Just as no Fortune 500 company would consider doing its bookkeeping by hand, the idea of leaving such important functionality to fallible humans will seem laughable at best and irresponsible at worst.</p>\n<p>Insurance companies will likely force this transition through higher business insurance rates for companies that allow humans to code. Policies already require certain business practices, such as daily backups, to get coverage. These policies are constantly updated to include technical best practices, and at some point, it will be a best practice to ensure no human makes direct edits to source code. All edits must be done through an AI that constantly checks for errors and security problems simultaneously.</p>\n<p>This transition is likely to take more time, but I’d bet that we start seeing the first glimpses of this approach as we approach 2030.</p>\n<h2 id="from-code-reviewer-to-task-verifier">From code reviewer to task verifier</h2>\n<p>As I’m writing this, AI is already capable of writing both source code and unit tests for that code. When integration tests already exist, AI is also capable of adding and modifying them. Right now, I haven’t experienced AI being able to set up a full integration test environment on its own, though I suspect this will change relatively quickly. The important human value added to the process is reviewing the code to ensure it meets requirements and follows associated best practices. At this stage, the source code serves primarily as a human auditing tool.</p>\n<p>Once AI is better than humans at writing code, it will also be better at reviewing code. Reviewing code is a bit more complex than writing it because you (or a model) need the correct context to understand the code. Nevertheless, AI will eventually meet this bar, and at that point, humans will no longer need to review the generated code. Through a series of non-deterministic and deterministic analysis, AI will identify any problems in the code and fix them automatically.</p>\n<p>In all likelihood, this will become part of the development process where one agent generates the code and another agent reviews it and provides feedback. The first agent then makes changes to address the feedback, triggering another review. The process continues until the code is deemed acceptable. Google Antigravity already implements something along these lines by having the agent generate and execute a verification plan<sup><a href="#user-content-fn-7" id="user-content-fnref-7" data-footnote-ref="" aria-describedby="footnote-label">7</a></sup> after code generation is complete.</p>\n<p>When the agents agree on the state of the code, the human’s job is reduced to verifying that the requested task is completed as specified. Even this step will rely more on artifacts generated by the agents rather than on reviewing code. For instance, instead of conducting a code review to determine that a button to create a new task was added, an agent will provide screenshots of the relevant new UI and a video showing the new interactions. If there are any problems, the human provides feedback and the coding agent makes the appropriate changes. Google Antigravity has already started down this path by taking screenshots and videos<sup><a href="#user-content-fn-8" id="user-content-fnref-8" data-footnote-ref="" aria-describedby="footnote-label">8</a></sup> of UI changes.</p>\n<p>The change will be automatically deployed after the human reviewer verifies the task is complete.</p>\n<p>Given that this is the way Google Antigravity currently works, I expect this approach to be common in 2028 and the norm by 2030.</p>\n<h2 id="future-programming-languages">Future programming languages</h2>\n<p>“Programs must be written for people to read, and only incidentally for machines to execute.”<br>\n― Harold Abelson, Structure and Interpretation of Computer Programs</p>\n<p>While AI currently uses existing programming languages, I don’t think that will necessarily remain the case. The current generation of higher-level languages was created to make programming easier for humans compared to manually executing processor instructions. In a world where humans don’t need to write or review code, the utility of these languages is significantly lessened, especially considering the extra tokens necessary to create visually appealing patterns for humans to recognize.</p>\n<p>More token-efficient programming languages can certainly be created, allowing AI to generate the same code using fewer resources. We already have Token-Oriented Object Notation<sup><a href="#user-content-fn-9" id="user-content-fnref-9" data-footnote-ref="" aria-describedby="footnote-label">9</a></sup> (TOON) as a more token-efficient alternative to JSON for use with LLMs. I don’t think new imperative languages are far off. Given the amount of AI-generated code we already have, and how much that will increase in the future, creating languages with more compact syntax could both increase the speed of code generation and reduce the cost.</p>\n<p>A common pushback to this point is that AI is only good at coding because it was trained on a massive amount of code spanning decades. That code represents both best practices and common patterns to be mimicked in generated code. While that’s true of today’s LLMs, I don’t think we should assume that all future models will need the same amount of training or sample data to produce functionally equivalent code in a new programming language. LLMs may not end up being the code generation model of choice as AI continues to evolve and new model types are created. It’s possible we’ll end up with a model that can write excellent code simply by reviewing the language specification and discovering best practices along the way.</p>\n<p>In the end, code will be written primarily for computers to execute and only incidentally for humans to read. A full transition to this approach may take until 2035 to have compilers and interpreters for new languages replace existing ones. However, new languages could be developed in the meantime to act as intermediate languages to be transpiled into their final form by deterministic tools.</p>\n<h2 id="from-engineering-teams-to-minimum-viable-engineering-teams-mvet">From engineering teams to minimum viable engineering teams (MVET)</h2>\n<p>In the new orchestrator role, a single engineer will guide multiple agents producing code equivalent to multiple engineers. The result will necessarily be smaller engineering teams with the bare minimum number of engineers to get the desired output. I call this a minimum viable engineering team (MVET). How small the MVET will be is based primarily on non-technical factors, such as:</p>\n<ul>\n<li><strong>Will a single engineer working in isolation be happy and dedicated?</strong> While many engineers claim they wish they could just do all the work themselves without dealing with the messiness of other humans, that might not be the reality. Humans are social creatures, and part of the fun is collaborating with others to solve interesting problems. There may be some minimum team size that’s optimal for productive engineers.</li>\n<li><strong>What value do companies place on eliminating single points of failure (SPOFs)?</strong> It may be tempting to have a single engineer, especially at a small company or startup, but what if that engineer goes on vacation, gets sick, or leaves? Or, knowing their worth, leverages their position for more pay or other concessions? It may be worth the extra payroll to have redundancy on the engineering team to eliminate this SPOF.</li>\n<li><strong>How important are subject matter experts?</strong> Will companies want to hire specialists or generalists? In a complex system, expecting one person to be an expert in all aspects of an application is unrealistic. Companies may still want a front-end expert, a back-end expert, and a database expert to orchestrate the agents associated with those areas.</li>\n<li><strong>What kind of a talent pipeline does the company want?</strong> Companies will want some continuity plan for when engineers leave. Having at least one senior and one junior engineer on a task both eliminates a SPOF while planning for a future in which the senior engineer leaves.</li>\n<li><strong>Does AI orchestration productivity increase with more engineers?</strong> We may discover that engineers are more effective orchestrators when they have other engineers to collaborate with. Traditional pair programming techniques such as driver-navigator<sup><a href="#user-content-fn-10" id="user-content-fnref-10" data-footnote-ref="" aria-describedby="footnote-label">10</a></sup> may reduce errors and produce higher-quality output. Even without following any strict collaboration setup, just having someone else to bounce ideas off of and provide a different perspective may yield better results. In that case, it would benefit the company to have at least two engineers per orchestration.</li>\n</ul>\n<p>There will undoubtedly be companies that try to pare down their engineering teams to the bare minimum. My hypothesis is that these companies will suffer as a result and eventually realize that an MVET is never just one person.</p>\n<p>Engineering teams will be smaller in the future, but how much smaller will vary by company. I’ve worked at many companies that overhired engineers because they were focused on the desired lines of code or parallelization necessary for a given project. With so much code needed, it was easy for subpar coders to find and keep well-paying jobs even as they underperformed. These individuals will not have software engineering jobs in the future. AI can already produce better quality code at a much lower cost.</p>\n<p>We’ve already seen the transition to smaller teams in 2025, and I think we’ll see a permanent rethinking of engineering team size by 2028.</p>\n<h2 id="from-delivering-code-to-delivering-value">From delivering code to delivering value</h2>\n<p>So who will have software engineering jobs? In the near term, the engineers who keep their jobs will show an aptitude not just for creating code but also for organizing work. These are typically skills people learn as they progress from junior engineer to senior engineer to tech lead and beyond. At that point, the job becomes less about delivering code and more about delivering value.</p>\n<p>Many tech leads are initially frustrated that they need to spend less time coding to take on other tasks like reviewing technical specifications and pull requests, mentoring, and assigning tasks. They’re frequently forced to start delegating work that they would otherwise prefer to do themselves. Eventually, though, tech leads relax into this role and understand that they can deliver value in many ways, not just through writing code. In fact, they can act as a multiplier on the team and make everyone else more productive.</p>\n<p>Future software engineers will need to behave more like tech leads right from the start of their careers. These are the skills I think will be important going forward:</p>\n<ul>\n<li><strong>Organization.</strong> Software development using agents means much more work to organize tasks across agents. Engineers will need to develop “flight plans” that map out how work will be split, parallelized, and merged to achieve the desired result. This includes logging and observability work to ensure traceability for agent workstreams.</li>\n<li><strong>Communication.</strong> With fewer engineers per team, ironically, communication among humans becomes more important. There will be much more cross-functional communication, and miscommunication is more likely to result in wasted work.</li>\n<li><strong>Systems thinking.</strong> Engineers will no longer be able to focus on a particular component in a system. Instead, they’ll need to think about how pieces fit together into a greater whole.</li>\n<li><strong>Model selection.</strong> Just as engineers today need to understand which languages to use for specific types of problems, we’ll also need to know which model is best suited for which types of tasks. Even within a particular model family, it’s important to know which generation and variant to use. For example, when is it better to use Claude 3.5 Sonnet vs. Claude 4.5 Haiku?</li>\n<li><strong>Prompt engineering.</strong> With all the agent interaction, writing prompts is a key skill. Prompts need to be specific enough to ensure agents aren’t wasting time misinterpreting commands. Practices like providing examples and counterexamples, using steps and lists, and breaking complex tasks into individual prompts are all important tools for this role.</li>\n<li><strong>Output validation.</strong> Much of an engineer’s job will be validating AI output. To do so, we will need to create deterministic workflows that can evaluate it. Engineers must have a good sense of when something is incomplete or error-prone before it deploys to production.</li>\n<li><strong>Debugging workflows.</strong> When agents don’t produce the desired result or the output isn’t working correctly, engineers will need to debug workflows to determine the source of the problem.</li>\n<li><strong>Agent-focused information management.</strong> Documentation is critical when agents are doing all the work. Information needs to be structured for AI consumption, and retrieval systems need to be available to agents so they can fetch the up-to-date data they need on demand.</li>\n<li><strong>Security.</strong> Making sure agents don’t access sensitive systems or fall victim to prompt injection attacks or jailbreaking will be a constant concern. Even cloud agents may be able to escape their sandbox, so this must be taken into account.</li>\n<li><strong>Budget management.</strong> Engineers may be given an AI budget on a weekly or monthly basis to keep costs in check. Whether that budget comes in the form of dollars, tokens, or credits, understanding the value you’ll get from a specific model’s output versus the cost to generate it will likely become an important skill.</li>\n</ul>\n<p>Up to this point, the ability to create functional code could land you an entry-level job as a software engineer. With code generation now commoditized through AI, this is no longer the case. The skills companies look for are already changing, making it more difficult for bootcamp-taught individuals to attain jobs. The necessary skills are those that are more difficult to teach and often hard-earned through on-the-job experience. As such, software engineering jobs will likely attract fewer people, as the “fun” part of the job is now being handled by AI and the more manager-like part of the job becomes more important.</p>\n<p>This transition is already taking place and I expect it to be mostly complete by 2028.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>The transition from coder to orchestrator represents a fundamental shift in how software is created. While the timeline for each phase varies, the direction is clear: humans will spend less time writing code and more time directing AI agents to do so. This isn’t a distant future scenario. The tools and practices described here are already emerging, with full adoption of orchestrator-based development likely within the next five years.</p>\n<p>This shift will be disruptive, particularly for those whose primary value proposition is writing code. Entry-level positions will become scarcer, and the barrier to entry will rise as companies seek engineers with organizational and strategic skills typically acquired through years of experience. However, for those who adapt, the role of software engineer will become more creative and strategic, focused on solving problems at a higher level of abstraction.</p>\n<p>The future of software engineering isn’t about humans versus AI. It’s about humans and AI working together, with humans providing the vision, judgment, and orchestration while AI handles the implementation details. Those who embrace this partnership and develop the skills to thrive in an orchestrator role will find themselves not replaced by AI, but empowered by it.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-1">\n<p><a href="https://addyo.substack.com/p/conductors-to-orchestrators-the-future">Conductors to Orchestrators: The Future of Agentic Coding</a> <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-2">\n<p><a href="https://cursor.com/docs/cloud-agent">Cloud Agents</a> <a href="#user-content-fnref-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-3">\n<p><a href="https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent">About GitHub Copilot coding agent</a> <a href="#user-content-fnref-3" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-4">\n<p><a href="https://github.com/copilot/agents">GitHub Mission Control</a> <a href="#user-content-fnref-4" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-5">\n<p><a href="https://code.visualstudio.com/docs/copilot/agents/overview#_manage-agent-sessions">Using agents in Visual Studio Code</a> <a href="#user-content-fnref-5" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-6">\n<p><a href="https://antigravity.google/">Google Antigravity</a> <a href="#user-content-fnref-6" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-7">\n<p><a href="https://youtu.be/htV29JrMXmA">Verification Plans in Google Antigravity</a> <a href="#user-content-fnref-7" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-8">\n<p><a href="https://antigravity.google/use-cases/frontend">Frontend - Google Antigravity</a> <a href="#user-content-fnref-8" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-9">\n<p><a href="https://toonformat.dev/">TOON - Token-Oriented Object Notation</a> <a href="#user-content-fnref-9" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-10">\n<p><a href="https://martinfowler.com/articles/on-pair-programming.html#Styles">On Pair Programming</a> <a href="#user-content-fnref-10" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n</ol>\n</section>","tags":["AI","Coder","Orchestrator","Automation"],"date_published":"2026-01-20T00:00:00.000Z","date_updated":"2026-01-20T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2026/01/how-github-could-secure-npm/","url":"https://humanwhocodes.com/blog/2026/01/how-github-could-secure-npm/","title":"How GitHub could secure npm","author":{"name":"Nicholas C. Zakas"},"summary":"Why doesn't npm detect compromised packages the way credit card companies detect fraud?","content_text":"\nIn 2025, npm experienced an unprecedented number of compromised packages in a series of coordinated attacks on the JavaScript open source supply chain. These packages ranged from crypto-stealing malware[^1] to credential-stealing exploits[^2]. While GitHub announced changes[^3] to address these attacks, many maintainers (myself included) found the response insufficient.\n\n## The impact of compromised packages\n\nThe scale of these attacks is staggering. In September 2025 alone, over 500 packages were compromised across two major attack waves. The first wave on September 8 compromised 20 widely-used packages with over 2 billion weekly downloads[^4]. Despite being live for only 2 hours, the compromised versions were downloaded 2.5 million times. The second wave, known as Shai-Hulud, was even more insidious: a self-replicating worm that automatically propagated across 500+ packages.\n\nWhile the total financial damage appears limited (approximately $500 in stolen cryptocurrency), the potential for significant harm is clear. If this was merely a test to gauge the feasibility of self-replicating attacks, we should prepare for more damaging attempts in the future.\n\n## The anatomy of an attack\n\nTo understand why npm's latest updates may fall short, it's important to understand how these attacks proceed.\n\n1. **Steal credentials.** Attackers steal the credentials of an existing npm maintainer, preferably someone with access to a high-traffic package or one frequently used by the intended target. Credentials are stolen either by compromising the maintainer's npm account (as in the case of Qix) or by stealing npm tokens (as in the Nx compromise[^5]). \n2. **Add a `preinstall` or `postinstall` script.** The attacker creates a malicious script that executes during the `preinstall` or `postinstall` phase of the npm package. This script runs automatically whenever `npm install` is executed, whether for the malicious package itself or any project using it. \n3. **Publish the compromised package.** The compromised package is published to the npm registry as a semver-patch update, increasing the likelihood it will be installed before the compromise is discovered.\n\n## How compromised packages spread\n\nCompromised packages are often installed quickly after publishing due to npm's default behavior. When using `npm install`, packages are added to `package.json` using a semver range beginning with a caret (`^`), such as `^1.2.3`. This tells npm to install any version starting with the given version (in this case, `1.2.3`) up to, but excluding, the next major version (`2.0.0`). So if `1.2.4` is the latest version, it will be installed instead of `1.2.3`. This behavior assumes packages follow semantic versioning, meaning non-major version bumps are always backwards compatible.\n\nAttackers exploit this behavior by publishing compromised versions as semver-patch or semver-minor increments. This ensures that anyone doing a fresh install of a project using the package will download the compromised version instead of a safe one, provided their version range includes the new version.\n\nWhile individuals may not do fresh installs frequently, continuous integration (CI) systems typically do. If not properly configured, CI systems can install the compromised package, potentially giving attackers access to cloud credentials that enable further attacks.\n\nUltimately, package consumers must take extra steps to avoid installing compromised packages, such as using lock files and immutable installs. However, npm's defaults still make it too easy to use version ranges that result in automatic installation of compromised packages.\n\n## GitHub’s response to the attacks\n\nIn September, GitHub announced its response[^6] to the attacks. The changes included:\n\n* Limiting publishing to local 2FA, granular access tokens[^7], and trusted publishing[^8]. \n* Deprecating legacy classic tokens and time-based one-time password (TOTP) 2FA. \n* Enforcing shorter expiration windows for granular tokens. \n* Disabling access tokens by default for new packages.\n\nThese steps targeted the Shai-Hulud attack[^9], which used a compromised package to scan for additional tokens and secrets. Those tokens and secrets were then used to publish more compromised packages, making the attack self-replicating.\n\nGitHub's response specifically targeted preventing future self-replicating attacks of this nature. Deprecating older, less secure legacy tokens helps limit the scope of an attack if a malicious actor obtains someone's credentials.\n\nHowever, the response has some limitations:\n\n* Reducing the usable lifetime of tokens only ensures that older, possibly forgotten tokens can’t be used in attacks. Infiltration of machines with up-to-date tokens yield the same results. \n* While promoting trusted publishing as an alternative to tokens makes sense for open source projects hosted on GitHub or GitLab, it leaves others without a viable option. npm currently only supports GitHub and GitLab as OpenID Connect (OIDC) providers, so maintainers not using these systems cannot use this feature. \n* The first publish of a new package can't use trusted publishing—it must be done with a token or locally using 2FA. \n* Trusted publishing is not yet complete, most notably its missing 2FA. This caused the Open JS Foundation to recommend not using trusted publishing[^10] for critical packages. \n* Maintainers of many packages now need to rotate tokens at least every 90 days, creating significant additional maintenance burden[^11]. \n* Maintainers of many packages must manually update every package through the npm web app, completing multiple 2FA verifications for each package. \n* Removing TOTP means maintainers always need a web browser available in the same environment as the publish operation. \n* The rapid rollout, along with shifting dates and lack of UI to accommodate common use cases, created confusion and frustration[^12] among maintainers.\n\nIn short, GitHub's response placed more responsibility on maintainers whose credentials were stolen and packages compromised. This created additional work for maintainers, especially those managing many packages. While these changes may reduce a certain type of attack, they don't address npm's systemic problems.\n\nProblems like this require a different approach. To understand what that might look like, it helps to examine another industry facing similar challenges.\n\n## How npm is like the credit card industry\n\nThe credit card industry faces challenges similar to npm's, except instead of compromised packages, they deal with fraudulent transactions. The attack vector is similar: both begin with stealing credentials. In this case, the credentials are credit card information rather than an npm login or token. I'm old enough to remember when stores would take imprints of credit cards and process all transactions in a batch at the end of the day. It was easy to commit fraud and never be caught using that system, so the credit card industry adapted.\n\nToday, credit cards have several ways to prevent credential theft:\n\n* The cards themselves have chips that are difficult to duplicate (as opposed to the old magnetic stripes), making it easier to authenticate a physical card. \n* In some countries, you must enter a PIN along with presenting the chipped card to make a transaction, adding second-factor authentication to the process. \n* When using a credit card online, you need to enter not just the number, but also the expiration date, CVC number, cardholder name, and sometimes the postal code. All of this helps ensure that someone possesses the physical card and not just the card number.\n\nEven so, credit card companies know that cards will still be stolen and used for fraudulent purchases, so they don't stop at these measures. They also monitor their networks for suspicious activity.\n\nIf you're a frequent credit card user, you've likely received a text or phone call asking if you made a particular transaction. That's the credit card company's algorithms flagging a transaction as outside your normal spending pattern. Maybe you typically make small purchases and suddenly buy a new kitchen appliance. It's not fraudulent, but it's unusual, so it gets flagged for verification. Maybe you travel to another state or country and use your credit card there. Again, it's not fraudulent, but it doesn't follow your typical usage pattern, so it's best to verify before allowing the transaction. This is called *anomaly detection*, a standard practice for identifying unwanted or unexpected data in data streams.\n\n## What npm got wrong\n\nGitHub's response to the ongoing supply chain attacks focused solely on credential theft, which is why it falls short. We already know how packages become compromised, and while securing credentials is important, we also know that credentials will inevitably be stolen.\n\nCredit card companies understand that fraudulent transactions will still occur regardless of how many additional factors they add to validation. That's why they invest in anomaly detection in addition to securing credentials. Once credentials are compromised, they still want to protect consumers and merchants from fraud.\n\nGitHub, on the other hand, has not invested in protecting the ecosystem from compromised packages as they are published. The latest changes place most of the responsibility on package maintainers. Long-time maintainer Qix fell victim to a convincing phishing attack—if even experienced maintainers can be compromised, less-seasoned maintainers face even greater risk.\n\nMeanwhile, GitHub continues taking down malicious packages after they've already caused damage. However, there are proactive measures GitHub could implement, such as investing in the same kind of anomaly detection that helps credit card companies flag fraudulent transactions.\n\n## What GitHub could do with npm\n\nInstead of continuing to focus solely on credential security, GitHub could analyze packages as they are published. (They already do this once they have identified Indicators of Compromise, effectively blocking new packages containing the same IoCs.) Given what we know about malicious packages, there are several ways the npm registry could be made more secure. Each of the following suggestions assumes the maintainer's npm account has been compromised and therefore we cannot rely on the npm web app for verification.\n\n### Location tracking of publishes\n\nSimilar to how credit card companies track purchase locations and flag unexpected transactions, the npm registry could flag package publishes that occur from an unexpected location. The npm registry likely already tracks the IP address of operations, which can be used to infer the location of the person or system publishing the package. If an `npm publish` operation occurs from a location significantly different from the previous publish, npm could require verification via email to at least one maintainer.\n\nBecause we are assuming the package owner's npm account has been compromised, npm 2FA offers little validation of the package owner's identity. Instead, npm could require the maintainer to retrieve a code sent to their email to publish a package from an unusual location. This would require the attacker to have access to both the npm account and the email account, significantly raising the bar for publishing a compromised package.\n\nWhat would count as an unusual location? Here are some examples:\n\n* The publish typically happens from a GitHub Actions datacenter but this one happens from outside the datacenter. \n* The publish typically happens from a location in Florida but this one happens in California. \n* The publish typically happens from a location in the United States but this one happens in China.\n\nThese heuristics can be tuned according to the actual patterns observed in the npm registry. Popular web apps like Gmail and Facebook use similar location tracking to proactively intervene when an account appears compromised.\n\n### Require semver-major version bumps when adding `preinstall` or `postinstall` scripts\n\nBecause these attacks frequently use `preinstall` or `postinstall` scripts on packages that didn't have one previously, detecting when a package is published with a `preinstall` or `postinstall` script for the first time is key. This could be done with a single bit indicating whether a major release line has a `preinstall` script and a single bit indicating whether it has a `postinstall` script. For instance, when `1.0.0` is published, the `1.x` release line bits are set to indicate whether it has either a `preinstall` or `postinstall` script.\n\nWhen the next version of the package is published in the same major release line (for example, `1.1.0` or `1.0.1`), check the bits of the `1.x` release line to see whether a `preinstall` script already exists. If the bit is set, there's no need to further investigate `preinstall` for this new version (`preinstall` is already allowed). If the bit is not set, check `package.json` to see whether a `preinstall` script exists. If it does, this is a violation and the package publish must fail. If desired, the package may be published as the next major version (in the previous example, `2.0.0`). Repeat the process with the `postinstall` bit.\n\nThis type of anomaly detection effectively removes one of the attacker's main weapons: the speed with which a compromised package is installed. Because forcing a semver-major version bump removes it from the default range for npm dependencies, it will not automatically be installed in most projects. Some projects with customized dependency ranges (such as `> 1.0.2`) will still be affected, but the majority will be safe. This delay will hopefully both dissuade some attackers and make it easier to detect problems before they affect too many systems.\n\n### Require email-based 2FA when adding `preinstall` or `postinstall` scripts\n\nIn addition to requiring a semver-major version bump when adding `preinstall` or `postinstall` scripts, npm could also enforce verification via email to publish a new version with a `preinstall` or `postinstall` script where one didn't previously exist. This could use the same email-based 2FA system as location anomaly detection.\n\n### Require double verification for invited maintainers\n\nThe current system for inviting maintainers to a package leaves a gap that could allow attackers to circumvent email-based 2FA. Because the invitation process is single opt-in on the part of the invitee, an attacker could compromise an npm account and then invite a separate npm account as a maintainer to receive any email-based 2FA requests. To prevent this, the invite system should be updated so that all current maintainers receive an email asking them to confirm they intended to invite the new maintainer. As long as one of the current maintainers approves, the invite will be sent to the new maintainer.\n\n## A plea to GitHub\n\nWe know you want to be responsible stewards of the JavaScript ecosystem. We know the npm registry requires significant effort to maintain and is costly to run. However, npm's infrastructure needs more attention and resources. The response to these attacks was reactive and implemented without gathering feedback from the community most affected. Now is the time to invest in proactive security measures that can protect the registry against what is certain to be an increasing number and intensity of attacks.\n\n## Conclusion\n\nGitHub has an opportunity to take a more proactive approach to securing the npm registry. Rather than placing the burden solely on maintainers to protect their credentials, GitHub could implement anomaly detection systems similar to those used by the credit card industry. The suggestions outlined here (location tracking, restrictions on lifecycle scripts, and improved verification processes) would create multiple layers of defense that work even after credentials are compromised. These measures wouldn't eliminate all supply chain attacks, but they would significantly reduce the window of opportunity for attackers and limit the damage compromised packages can cause. Most importantly, they would demonstrate a commitment to protecting the entire JavaScript ecosystem, not just responding to attacks after they've already succeeded. The technology and patterns for these protections already exist in other industries. It's time for GitHub to apply them to npm.\n\n[^1]: [npm Author Qix Compromised via Phishing Email in Major Supply Chain Attack](https://socket.dev/blog/npm-author-qix-compromised-in-major-supply-chain-attack)\n[^2]: [Popular Tinycolor npm Package Compromised in Supply Chain Attack Affecting 40+ Packages](https://socket.dev/blog/tinycolor-supply-chain-attack-affects-40-packages)\n[^3]: [Our plan for a more secure npm supply chain](https://github.blog/security/supply-chain-security/our-plan-for-a-more-secure-npm-supply-chain/)\n[^4]: [New compromised packages identified in largest npm attack in history](https://jfrog.com/blog/new-compromised-packages-in-largest-npm-attack-in-history/)\n[^5]: [Nx Investigation Reveals GitHub Actions Workflow Exploit Led to npm Token Theft, Prompting Switch to Trusted Publishing](https://socket.dev/blog/nx-supply-chain-attack-investigation-github-actions-workflow-exploit)\n[^6]: [Our plan for a more secure npm supply chain](https://github.blog/security/supply-chain-security/our-plan-for-a-more-secure-npm-supply-chain/)\n[^7]: [About granular access tokens](https://docs.npmjs.com/about-access-tokens#about-granular-access-tokens)\n[^8]: [Trusted Publishers for All Package Repositories](https://repos.openssf.org/trusted-publishers-for-all-package-repositories)\n[^9]: [Updated and Ongoing Supply Chain Attack Targets CrowdStrike npm Packages](https://socket.dev/blog/ongoing-supply-chain-attack-targets-crowdstrike-npm-packages)\n[^10]: [Publishing More Securely on npm: Guidance from the OpenJS Security Collaboration Space](https://openjsf.org/blog/publishing-securely-on-npm)\n[^11]: [Comment: Classic token removal moves to December 9, bundled with new CLI improvements](https://github.com/orgs/community/discussions/179562#discussioncomment-15221604)\n[^12]: [Update: Classic token removal moves to December 9, bundled with new CLI improvements](https://github.com/orgs/community/discussions/179562)\n","content_html":"<p>In 2025, npm experienced an unprecedented number of compromised packages in a series of coordinated attacks on the JavaScript open source supply chain. These packages ranged from crypto-stealing malware<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> to credential-stealing exploits<sup><a href="#user-content-fn-2" id="user-content-fnref-2" data-footnote-ref="" aria-describedby="footnote-label">2</a></sup>. While GitHub announced changes<sup><a href="#user-content-fn-3" id="user-content-fnref-3" data-footnote-ref="" aria-describedby="footnote-label">3</a></sup> to address these attacks, many maintainers (myself included) found the response insufficient.</p>\n<h2 id="the-impact-of-compromised-packages">The impact of compromised packages</h2>\n<p>The scale of these attacks is staggering. In September 2025 alone, over 500 packages were compromised across two major attack waves. The first wave on September 8 compromised 20 widely-used packages with over 2 billion weekly downloads<sup><a href="#user-content-fn-4" id="user-content-fnref-4" data-footnote-ref="" aria-describedby="footnote-label">4</a></sup>. Despite being live for only 2 hours, the compromised versions were downloaded 2.5 million times. The second wave, known as Shai-Hulud, was even more insidious: a self-replicating worm that automatically propagated across 500+ packages.</p>\n<p>While the total financial damage appears limited (approximately $500 in stolen cryptocurrency), the potential for significant harm is clear. If this was merely a test to gauge the feasibility of self-replicating attacks, we should prepare for more damaging attempts in the future.</p>\n<h2 id="the-anatomy-of-an-attack">The anatomy of an attack</h2>\n<p>To understand why npm’s latest updates may fall short, it’s important to understand how these attacks proceed.</p>\n<ol>\n<li><strong>Steal credentials.</strong> Attackers steal the credentials of an existing npm maintainer, preferably someone with access to a high-traffic package or one frequently used by the intended target. Credentials are stolen either by compromising the maintainer’s npm account (as in the case of Qix) or by stealing npm tokens (as in the Nx compromise<sup><a href="#user-content-fn-5" id="user-content-fnref-5" data-footnote-ref="" aria-describedby="footnote-label">5</a></sup>).</li>\n<li><strong>Add a <code>preinstall</code> or <code>postinstall</code> script.</strong> The attacker creates a malicious script that executes during the <code>preinstall</code> or <code>postinstall</code> phase of the npm package. This script runs automatically whenever <code>npm install</code> is executed, whether for the malicious package itself or any project using it.</li>\n<li><strong>Publish the compromised package.</strong> The compromised package is published to the npm registry as a semver-patch update, increasing the likelihood it will be installed before the compromise is discovered.</li>\n</ol>\n<h2 id="how-compromised-packages-spread">How compromised packages spread</h2>\n<p>Compromised packages are often installed quickly after publishing due to npm’s default behavior. When using <code>npm install</code>, packages are added to <code>package.json</code> using a semver range beginning with a caret (<code>^</code>), such as <code>^1.2.3</code>. This tells npm to install any version starting with the given version (in this case, <code>1.2.3</code>) up to, but excluding, the next major version (<code>2.0.0</code>). So if <code>1.2.4</code> is the latest version, it will be installed instead of <code>1.2.3</code>. This behavior assumes packages follow semantic versioning, meaning non-major version bumps are always backwards compatible.</p>\n<p>Attackers exploit this behavior by publishing compromised versions as semver-patch or semver-minor increments. This ensures that anyone doing a fresh install of a project using the package will download the compromised version instead of a safe one, provided their version range includes the new version.</p>\n<p>While individuals may not do fresh installs frequently, continuous integration (CI) systems typically do. If not properly configured, CI systems can install the compromised package, potentially giving attackers access to cloud credentials that enable further attacks.</p>\n<p>Ultimately, package consumers must take extra steps to avoid installing compromised packages, such as using lock files and immutable installs. However, npm’s defaults still make it too easy to use version ranges that result in automatic installation of compromised packages.</p>\n<h2 id="githubs-response-to-the-attacks">GitHub’s response to the attacks</h2>\n<p>In September, GitHub announced its response<sup><a href="#user-content-fn-6" id="user-content-fnref-6" data-footnote-ref="" aria-describedby="footnote-label">6</a></sup> to the attacks. The changes included:</p>\n<ul>\n<li>Limiting publishing to local 2FA, granular access tokens<sup><a href="#user-content-fn-7" id="user-content-fnref-7" data-footnote-ref="" aria-describedby="footnote-label">7</a></sup>, and trusted publishing<sup><a href="#user-content-fn-8" id="user-content-fnref-8" data-footnote-ref="" aria-describedby="footnote-label">8</a></sup>.</li>\n<li>Deprecating legacy classic tokens and time-based one-time password (TOTP) 2FA.</li>\n<li>Enforcing shorter expiration windows for granular tokens.</li>\n<li>Disabling access tokens by default for new packages.</li>\n</ul>\n<p>These steps targeted the Shai-Hulud attack<sup><a href="#user-content-fn-9" id="user-content-fnref-9" data-footnote-ref="" aria-describedby="footnote-label">9</a></sup>, which used a compromised package to scan for additional tokens and secrets. Those tokens and secrets were then used to publish more compromised packages, making the attack self-replicating.</p>\n<p>GitHub’s response specifically targeted preventing future self-replicating attacks of this nature. Deprecating older, less secure legacy tokens helps limit the scope of an attack if a malicious actor obtains someone’s credentials.</p>\n<p>However, the response has some limitations:</p>\n<ul>\n<li>Reducing the usable lifetime of tokens only ensures that older, possibly forgotten tokens can’t be used in attacks. Infiltration of machines with up-to-date tokens yield the same results.</li>\n<li>While promoting trusted publishing as an alternative to tokens makes sense for open source projects hosted on GitHub or GitLab, it leaves others without a viable option. npm currently only supports GitHub and GitLab as OpenID Connect (OIDC) providers, so maintainers not using these systems cannot use this feature.</li>\n<li>The first publish of a new package can’t use trusted publishing—it must be done with a token or locally using 2FA.</li>\n<li>Trusted publishing is not yet complete, most notably its missing 2FA. This caused the Open JS Foundation to recommend not using trusted publishing<sup><a href="#user-content-fn-10" id="user-content-fnref-10" data-footnote-ref="" aria-describedby="footnote-label">10</a></sup> for critical packages.</li>\n<li>Maintainers of many packages now need to rotate tokens at least every 90 days, creating significant additional maintenance burden<sup><a href="#user-content-fn-11" id="user-content-fnref-11" data-footnote-ref="" aria-describedby="footnote-label">11</a></sup>.</li>\n<li>Maintainers of many packages must manually update every package through the npm web app, completing multiple 2FA verifications for each package.</li>\n<li>Removing TOTP means maintainers always need a web browser available in the same environment as the publish operation.</li>\n<li>The rapid rollout, along with shifting dates and lack of UI to accommodate common use cases, created confusion and frustration<sup><a href="#user-content-fn-12" id="user-content-fnref-12" data-footnote-ref="" aria-describedby="footnote-label">12</a></sup> among maintainers.</li>\n</ul>\n<p>In short, GitHub’s response placed more responsibility on maintainers whose credentials were stolen and packages compromised. This created additional work for maintainers, especially those managing many packages. While these changes may reduce a certain type of attack, they don’t address npm’s systemic problems.</p>\n<p>Problems like this require a different approach. To understand what that might look like, it helps to examine another industry facing similar challenges.</p>\n<h2 id="how-npm-is-like-the-credit-card-industry">How npm is like the credit card industry</h2>\n<p>The credit card industry faces challenges similar to npm’s, except instead of compromised packages, they deal with fraudulent transactions. The attack vector is similar: both begin with stealing credentials. In this case, the credentials are credit card information rather than an npm login or token. I’m old enough to remember when stores would take imprints of credit cards and process all transactions in a batch at the end of the day. It was easy to commit fraud and never be caught using that system, so the credit card industry adapted.</p>\n<p>Today, credit cards have several ways to prevent credential theft:</p>\n<ul>\n<li>The cards themselves have chips that are difficult to duplicate (as opposed to the old magnetic stripes), making it easier to authenticate a physical card.</li>\n<li>In some countries, you must enter a PIN along with presenting the chipped card to make a transaction, adding second-factor authentication to the process.</li>\n<li>When using a credit card online, you need to enter not just the number, but also the expiration date, CVC number, cardholder name, and sometimes the postal code. All of this helps ensure that someone possesses the physical card and not just the card number.</li>\n</ul>\n<p>Even so, credit card companies know that cards will still be stolen and used for fraudulent purchases, so they don’t stop at these measures. They also monitor their networks for suspicious activity.</p>\n<p>If you’re a frequent credit card user, you’ve likely received a text or phone call asking if you made a particular transaction. That’s the credit card company’s algorithms flagging a transaction as outside your normal spending pattern. Maybe you typically make small purchases and suddenly buy a new kitchen appliance. It’s not fraudulent, but it’s unusual, so it gets flagged for verification. Maybe you travel to another state or country and use your credit card there. Again, it’s not fraudulent, but it doesn’t follow your typical usage pattern, so it’s best to verify before allowing the transaction. This is called <em>anomaly detection</em>, a standard practice for identifying unwanted or unexpected data in data streams.</p>\n<h2 id="what-npm-got-wrong">What npm got wrong</h2>\n<p>GitHub’s response to the ongoing supply chain attacks focused solely on credential theft, which is why it falls short. We already know how packages become compromised, and while securing credentials is important, we also know that credentials will inevitably be stolen.</p>\n<p>Credit card companies understand that fraudulent transactions will still occur regardless of how many additional factors they add to validation. That’s why they invest in anomaly detection in addition to securing credentials. Once credentials are compromised, they still want to protect consumers and merchants from fraud.</p>\n<p>GitHub, on the other hand, has not invested in protecting the ecosystem from compromised packages as they are published. The latest changes place most of the responsibility on package maintainers. Long-time maintainer Qix fell victim to a convincing phishing attack—if even experienced maintainers can be compromised, less-seasoned maintainers face even greater risk.</p>\n<p>Meanwhile, GitHub continues taking down malicious packages after they’ve already caused damage. However, there are proactive measures GitHub could implement, such as investing in the same kind of anomaly detection that helps credit card companies flag fraudulent transactions.</p>\n<h2 id="what-github-could-do-with-npm">What GitHub could do with npm</h2>\n<p>Instead of continuing to focus solely on credential security, GitHub could analyze packages as they are published. (They already do this once they have identified Indicators of Compromise, effectively blocking new packages containing the same IoCs.) Given what we know about malicious packages, there are several ways the npm registry could be made more secure. Each of the following suggestions assumes the maintainer’s npm account has been compromised and therefore we cannot rely on the npm web app for verification.</p>\n<h3 id="location-tracking-of-publishes">Location tracking of publishes</h3>\n<p>Similar to how credit card companies track purchase locations and flag unexpected transactions, the npm registry could flag package publishes that occur from an unexpected location. The npm registry likely already tracks the IP address of operations, which can be used to infer the location of the person or system publishing the package. If an <code>npm publish</code> operation occurs from a location significantly different from the previous publish, npm could require verification via email to at least one maintainer.</p>\n<p>Because we are assuming the package owner’s npm account has been compromised, npm 2FA offers little validation of the package owner’s identity. Instead, npm could require the maintainer to retrieve a code sent to their email to publish a package from an unusual location. This would require the attacker to have access to both the npm account and the email account, significantly raising the bar for publishing a compromised package.</p>\n<p>What would count as an unusual location? Here are some examples:</p>\n<ul>\n<li>The publish typically happens from a GitHub Actions datacenter but this one happens from outside the datacenter.</li>\n<li>The publish typically happens from a location in Florida but this one happens in California.</li>\n<li>The publish typically happens from a location in the United States but this one happens in China.</li>\n</ul>\n<p>These heuristics can be tuned according to the actual patterns observed in the npm registry. Popular web apps like Gmail and Facebook use similar location tracking to proactively intervene when an account appears compromised.</p>\n<h3 id="require-semver-major-version-bumps-when-adding-preinstall-or--postinstall-scripts">Require semver-major version bumps when adding <code>preinstall</code> or <code>postinstall</code> scripts</h3>\n<p>Because these attacks frequently use <code>preinstall</code> or <code>postinstall</code> scripts on packages that didn’t have one previously, detecting when a package is published with a <code>preinstall</code> or <code>postinstall</code> script for the first time is key. This could be done with a single bit indicating whether a major release line has a <code>preinstall</code> script and a single bit indicating whether it has a <code>postinstall</code> script. For instance, when <code>1.0.0</code> is published, the <code>1.x</code> release line bits are set to indicate whether it has either a <code>preinstall</code> or <code>postinstall</code> script.</p>\n<p>When the next version of the package is published in the same major release line (for example, <code>1.1.0</code> or <code>1.0.1</code>), check the bits of the <code>1.x</code> release line to see whether a <code>preinstall</code> script already exists. If the bit is set, there’s no need to further investigate <code>preinstall</code> for this new version (<code>preinstall</code> is already allowed). If the bit is not set, check <code>package.json</code> to see whether a <code>preinstall</code> script exists. If it does, this is a violation and the package publish must fail. If desired, the package may be published as the next major version (in the previous example, <code>2.0.0</code>). Repeat the process with the <code>postinstall</code> bit.</p>\n<p>This type of anomaly detection effectively removes one of the attacker’s main weapons: the speed with which a compromised package is installed. Because forcing a semver-major version bump removes it from the default range for npm dependencies, it will not automatically be installed in most projects. Some projects with customized dependency ranges (such as <code>> 1.0.2</code>) will still be affected, but the majority will be safe. This delay will hopefully both dissuade some attackers and make it easier to detect problems before they affect too many systems.</p>\n<h3 id="require-email-based-2fa-when-adding-preinstall-or-postinstall-scripts">Require email-based 2FA when adding <code>preinstall</code> or <code>postinstall</code> scripts</h3>\n<p>In addition to requiring a semver-major version bump when adding <code>preinstall</code> or <code>postinstall</code> scripts, npm could also enforce verification via email to publish a new version with a <code>preinstall</code> or <code>postinstall</code> script where one didn’t previously exist. This could use the same email-based 2FA system as location anomaly detection.</p>\n<h3 id="require-double-verification-for-invited-maintainers">Require double verification for invited maintainers</h3>\n<p>The current system for inviting maintainers to a package leaves a gap that could allow attackers to circumvent email-based 2FA. Because the invitation process is single opt-in on the part of the invitee, an attacker could compromise an npm account and then invite a separate npm account as a maintainer to receive any email-based 2FA requests. To prevent this, the invite system should be updated so that all current maintainers receive an email asking them to confirm they intended to invite the new maintainer. As long as one of the current maintainers approves, the invite will be sent to the new maintainer.</p>\n<h2 id="a-plea-to-github">A plea to GitHub</h2>\n<p>We know you want to be responsible stewards of the JavaScript ecosystem. We know the npm registry requires significant effort to maintain and is costly to run. However, npm’s infrastructure needs more attention and resources. The response to these attacks was reactive and implemented without gathering feedback from the community most affected. Now is the time to invest in proactive security measures that can protect the registry against what is certain to be an increasing number and intensity of attacks.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>GitHub has an opportunity to take a more proactive approach to securing the npm registry. Rather than placing the burden solely on maintainers to protect their credentials, GitHub could implement anomaly detection systems similar to those used by the credit card industry. The suggestions outlined here (location tracking, restrictions on lifecycle scripts, and improved verification processes) would create multiple layers of defense that work even after credentials are compromised. These measures wouldn’t eliminate all supply chain attacks, but they would significantly reduce the window of opportunity for attackers and limit the damage compromised packages can cause. Most importantly, they would demonstrate a commitment to protecting the entire JavaScript ecosystem, not just responding to attacks after they’ve already succeeded. The technology and patterns for these protections already exist in other industries. It’s time for GitHub to apply them to npm.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-1">\n<p><a href="https://socket.dev/blog/npm-author-qix-compromised-in-major-supply-chain-attack">npm Author Qix Compromised via Phishing Email in Major Supply Chain Attack</a> <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-2">\n<p><a href="https://socket.dev/blog/tinycolor-supply-chain-attack-affects-40-packages">Popular Tinycolor npm Package Compromised in Supply Chain Attack Affecting 40+ Packages</a> <a href="#user-content-fnref-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-3">\n<p><a href="https://github.blog/security/supply-chain-security/our-plan-for-a-more-secure-npm-supply-chain/">Our plan for a more secure npm supply chain</a> <a href="#user-content-fnref-3" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-4">\n<p><a href="https://jfrog.com/blog/new-compromised-packages-in-largest-npm-attack-in-history/">New compromised packages identified in largest npm attack in history</a> <a href="#user-content-fnref-4" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-5">\n<p><a href="https://socket.dev/blog/nx-supply-chain-attack-investigation-github-actions-workflow-exploit">Nx Investigation Reveals GitHub Actions Workflow Exploit Led to npm Token Theft, Prompting Switch to Trusted Publishing</a> <a href="#user-content-fnref-5" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-6">\n<p><a href="https://github.blog/security/supply-chain-security/our-plan-for-a-more-secure-npm-supply-chain/">Our plan for a more secure npm supply chain</a> <a href="#user-content-fnref-6" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-7">\n<p><a href="https://docs.npmjs.com/about-access-tokens#about-granular-access-tokens">About granular access tokens</a> <a href="#user-content-fnref-7" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-8">\n<p><a href="https://repos.openssf.org/trusted-publishers-for-all-package-repositories">Trusted Publishers for All Package Repositories</a> <a href="#user-content-fnref-8" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-9">\n<p><a href="https://socket.dev/blog/ongoing-supply-chain-attack-targets-crowdstrike-npm-packages">Updated and Ongoing Supply Chain Attack Targets CrowdStrike npm Packages</a> <a href="#user-content-fnref-9" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-10">\n<p><a href="https://openjsf.org/blog/publishing-securely-on-npm">Publishing More Securely on npm: Guidance from the OpenJS Security Collaboration Space</a> <a href="#user-content-fnref-10" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-11">\n<p><a href="https://github.com/orgs/community/discussions/179562#discussioncomment-15221604">Comment: Classic token removal moves to December 9, bundled with new CLI improvements</a> <a href="#user-content-fnref-11" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n<li id="user-content-fn-12">\n<p><a href="https://github.com/orgs/community/discussions/179562">Update: Classic token removal moves to December 9, bundled with new CLI improvements</a> <a href="#user-content-fnref-12" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a></p>\n</li>\n</ol>\n</section>","tags":["GitHub","npm","Security"],"date_published":"2026-01-06T00:00:00.000Z","date_updated":"2026-01-06T00:00:00.000Z"},{"id":"https://humanwhocodes.com/snippets/2025/08/setup-local-supabase-oauth-logins/","url":"https://humanwhocodes.com/snippets/2025/08/setup-local-supabase-oauth-logins/","title":"Set up local Supabase OAuth logins","author":{"name":"Nicholas C. Zakas"},"summary":"While it's easy to set up Supabase OAuth logins in the cloud product, setting it up for a local development environment is a bit tricky.","content_text":"\nOne of the benefits of [Supabase](https://supabase.com) is its integrated login system that supports many OAuth providers, including Google and GitHub. While there is plenty of documentation explaining how to set up OAuth providers in hosted Supabase, the [instructions for local Supabase](https://supabase.com/docs/guides/local-development/overview#use-auth-locally) are fairly terse and are missing several steps. \n\nFirst, create a callback endpoint in your application, for example, `/auth/callback`. This is the callback that will receive the OAuth information from Supabase. Specifically, you should receive either a `code` query string parameter that will allow the user to login or an `error` parameter indicating there was an error logging in. Note that for server-side authentication you must use [`@supabase/ssr`](https://npmjs.com/package/@supabase/ssr). Here's an example written using [Astro](https://astro.build).\n\n```ts\n// Astro example\nimport { createServerClient, parseCookieHeader } from \"@supabase/ssr\";\n\nconst supabaseUrl = import.meta.env.SUPABASE_URL;\nconst supabaseAnonKey = import.meta.env.SUPABASE_ANON_KEY;\n\nexport const GET: APIRoute = async ({ url, request, cookies, redirect }) => {\n\n // if there's no code then redirect to login\n const code = url.searchParams.get(\"code\");\n if (!code) {\n redirect(\"/login?error=no-code\");\n }\n \n // there is a code, try to log in\n const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n cookies: {\n getAll() {\n return parseCookieHeader(request.headers.get(\"cookie\") || \"\");\n },\n setAll(cookiesToSet) {\n cookiesToSet.forEach(({ name, value, options }) =>\n cookies.set(name, value, options)\n );\n },\n },\n });\n \n const { data, error } = await supabase.auth.exchangeCodeForSession(code);\n if (error || !data?.session) {\n return redirect(\"/login?error=unauthorized\");\n }\n\n return redirect(\"/\");\n}\n```\n\nWith the callback set up, you now need to let Supabase know how to call it. In general, there are three steps to the OAuth login process for Supabase:\n\n1. Your application links off to the OAuth provider's authentication service.\n2. The OAuth provider redirects to the Supabase auth service.\n3. Supabase redirects to your application callback.\n\nTo ensure that happens locally, you need to edit the `config.toml` file. First, locate the `[auth]` section at the top and make sure the value for `site_url` is your local application URL and `additional_redirect_urls` contains the full URL for the callback endpoint. Here's an example:\n\n```toml\n[auth]\nenabled = true\n# The base URL of your website. Used as an allow-list for redirects and for constructing URLs used\n# in emails.\nsite_url = \"http://localhost:4321\"\n# A list of *exact* URLs that auth providers are permitted to redirect to post authentication.\nadditional_redirect_urls = [\"http://localhost:4321/auth/callback\"]\n```\n\n(Without specifying `additional_redirect_urls`, you'll always have to redirect back to the application homepage.)\n\nNext, create an entry for your OAuth provider including the client ID, client secret, and redirect URI. For GitHub, it would look like this:\n\n```toml\n[auth.external.github]\nenabled = true\nclient_id = \"env(GITHUB_CLIENT_ID)\"\nsecret = \"env(GITHUB_CLIENT_SECRET)\"\nredirect_uri = \"http://localhost:54321/auth/v1/callback\"\n```\n\nThe `redirect_uri` here needs to be the local Supabase URL for OAuth callbacks. The default port is 54321, so double-check the port.\n\nAfter editing `config.toml`, you need to restart Supabase to reload the configuration:\n\n```shell\nnpx supabase stop\nnpx supabase start\n```\n\nNext, you need to generate the OAuth URL to use in your application. Here's an example generating a URL to login with GitHub:\n\n```ts\nimport { createServerClient, parseCookieHeader } from \"@supabase/ssr\";\n\nconst supabaseUrl = import.meta.env.SUPABASE_URL;\nconst supabaseAnonKey = import.meta.env.SUPABASE_ANON_KEY;\n\nconst supabaseUrl = import.meta.env.SUPABASE_URL;\nconst supabaseAnonKey = import.meta.env.SUPABASE_ANON_KEY;\n\nexport const GET: APIRoute = async ({ url, request, cookies, redirect }) => {\n\n // if there's no code then redirect to login\n const code = url.searchParams.get(\"code\");\n if (!code) {\n redirect(\"/login?error=no-code\");\n }\n \n // there is a code, try to log in\n const supabase = createServerClient(supabaseUrl, supabaseAnonKey, {\n cookies: {\n getAll() {\n return parseCookieHeader(request.headers.get(\"cookie\") || \"\");\n },\n setAll(cookiesToSet) {\n cookiesToSet.forEach(({ name, value, options }) =>\n cookies.set(name, value, options)\n );\n },\n },\n });\n \n const { data, error } = await supabase.auth.signInWithOAuth({\n provider: \"github\",\n options: {\n // must be listed as additional_redirect_urls\n redirectTo: `http://localhost:4321/auth/callback`\n }\n });\n\n if (error || !data?.url) {\n // handle error\n }\n\n redirect(data.url);\n}\n```\n\nEverything is now wired up for the correct end-to-end flow.\n","content_html":"<p>One of the benefits of <a href="https://supabase.com">Supabase</a> is its integrated login system that supports many OAuth providers, including Google and GitHub. While there is plenty of documentation explaining how to set up OAuth providers in hosted Supabase, the <a href="https://supabase.com/docs/guides/local-development/overview#use-auth-locally">instructions for local Supabase</a> are fairly terse and are missing several steps.</p>\n<p>First, create a callback endpoint in your application, for example, <code>/auth/callback</code>. This is the callback that will receive the OAuth information from Supabase. Specifically, you should receive either a <code>code</code> query string parameter that will allow the user to login or an <code>error</code> parameter indicating there was an error logging in. Note that for server-side authentication you must use <a href="https://npmjs.com/package/@supabase/ssr"><code>@supabase/ssr</code></a>. Here’s an example written using <a href="https://astro.build">Astro</a>.</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #6A737D">// Astro example</span></span>\n<span class="line"><span style="color: #F97583">import</span><span style="color: #E1E4E8"> { createServerClient, parseCookieHeader } </span><span style="color: #F97583">from</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"@supabase/ssr"</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseUrl</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_URL</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseAnonKey</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_ANON_KEY</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">GET</span><span style="color: #F97583">:</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">APIRoute</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">async</span><span style="color: #E1E4E8"> ({ </span><span style="color: #FFAB70">url</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">request</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">cookies</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">redirect</span><span style="color: #E1E4E8"> }) </span><span style="color: #F97583">=></span><span style="color: #E1E4E8"> {</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// if there's no code then redirect to login</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">code</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> url.searchParams.</span><span style="color: #B392F0">get</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"code"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">if</span><span style="color: #E1E4E8"> (</span><span style="color: #F97583">!</span><span style="color: #E1E4E8">code) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">redirect</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"/login?error=no-code"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// there is a code, try to log in</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">createServerClient</span><span style="color: #E1E4E8">(supabaseUrl, supabaseAnonKey, {</span></span>\n<span class="line"><span style="color: #E1E4E8"> cookies: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">getAll</span><span style="color: #E1E4E8">() {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">parseCookieHeader</span><span style="color: #E1E4E8">(request.headers.</span><span style="color: #B392F0">get</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"cookie"</span><span style="color: #E1E4E8">) </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">""</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">setAll</span><span style="color: #E1E4E8">(</span><span style="color: #FFAB70">cookiesToSet</span><span style="color: #E1E4E8">) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> cookiesToSet.</span><span style="color: #B392F0">forEach</span><span style="color: #E1E4E8">(({ </span><span style="color: #FFAB70">name</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">value</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">options</span><span style="color: #E1E4E8"> }) </span><span style="color: #F97583">=></span></span>\n<span class="line"><span style="color: #E1E4E8"> cookies.</span><span style="color: #B392F0">set</span><span style="color: #E1E4E8">(name, value, options)</span></span>\n<span class="line"><span style="color: #E1E4E8"> );</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> });</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> { </span><span style="color: #79B8FF">data</span><span style="color: #E1E4E8">, </span><span style="color: #79B8FF">error</span><span style="color: #E1E4E8"> } </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> supabase.auth.</span><span style="color: #B392F0">exchangeCodeForSession</span><span style="color: #E1E4E8">(code);</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">if</span><span style="color: #E1E4E8"> (error </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">!</span><span style="color: #E1E4E8">data?.session) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">redirect</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"/login?error=unauthorized"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">redirect</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"/"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>With the callback set up, you now need to let Supabase know how to call it. In general, there are three steps to the OAuth login process for Supabase:</p>\n<ol>\n<li>Your application links off to the OAuth provider’s authentication service.</li>\n<li>The OAuth provider redirects to the Supabase auth service.</li>\n<li>Supabase redirects to your application callback.</li>\n</ol>\n<p>To ensure that happens locally, you need to edit the <code>config.toml</code> file. First, locate the <code>[auth]</code> section at the top and make sure the value for <code>site_url</code> is your local application URL and <code>additional_redirect_urls</code> contains the full URL for the callback endpoint. Here’s an example:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">[</span><span style="color: #B392F0">auth</span><span style="color: #E1E4E8">]</span></span>\n<span class="line"><span style="color: #E1E4E8">enabled = </span><span style="color: #79B8FF">true</span></span>\n<span class="line"><span style="color: #6A737D"># The base URL of your website. Used as an allow-list for redirects and for constructing URLs used</span></span>\n<span class="line"><span style="color: #6A737D"># in emails.</span></span>\n<span class="line"><span style="color: #E1E4E8">site_url = </span><span style="color: #9ECBFF">"http://localhost:4321"</span></span>\n<span class="line"><span style="color: #6A737D"># A list of *exact* URLs that auth providers are permitted to redirect to post authentication.</span></span>\n<span class="line"><span style="color: #E1E4E8">additional_redirect_urls = [</span><span style="color: #9ECBFF">"http://localhost:4321/auth/callback"</span><span style="color: #E1E4E8">]</span></span></code></pre>\n<p>(Without specifying <code>additional_redirect_urls</code>, you’ll always have to redirect back to the application homepage.)</p>\n<p>Next, create an entry for your OAuth provider including the client ID, client secret, and redirect URI. For GitHub, it would look like this:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">[</span><span style="color: #B392F0">auth</span><span style="color: #E1E4E8">.</span><span style="color: #B392F0">external</span><span style="color: #E1E4E8">.</span><span style="color: #B392F0">github</span><span style="color: #E1E4E8">]</span></span>\n<span class="line"><span style="color: #E1E4E8">enabled = </span><span style="color: #79B8FF">true</span></span>\n<span class="line"><span style="color: #E1E4E8">client_id = </span><span style="color: #9ECBFF">"env(GITHUB_CLIENT_ID)"</span></span>\n<span class="line"><span style="color: #E1E4E8">secret = </span><span style="color: #9ECBFF">"env(GITHUB_CLIENT_SECRET)"</span></span>\n<span class="line"><span style="color: #E1E4E8">redirect_uri = </span><span style="color: #9ECBFF">"http://localhost:54321/auth/v1/callback"</span></span></code></pre>\n<p>The <code>redirect_uri</code> here needs to be the local Supabase URL for OAuth callbacks. The default port is 54321, so double-check the port.</p>\n<p>After editing <code>config.toml</code>, you need to restart Supabase to reload the configuration:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">stop</span></span>\n<span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">start</span></span></code></pre>\n<p>Next, you need to generate the OAuth URL to use in your application. Here’s an example generating a URL to login with GitHub:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">import</span><span style="color: #E1E4E8"> { createServerClient, parseCookieHeader } </span><span style="color: #F97583">from</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"@supabase/ssr"</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseUrl</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_URL</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseAnonKey</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_ANON_KEY</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseUrl</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_URL</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabaseAnonKey</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">import</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">meta</span><span style="color: #E1E4E8">.env.</span><span style="color: #79B8FF">SUPABASE_ANON_KEY</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">GET</span><span style="color: #F97583">:</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">APIRoute</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">async</span><span style="color: #E1E4E8"> ({ </span><span style="color: #FFAB70">url</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">request</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">cookies</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">redirect</span><span style="color: #E1E4E8"> }) </span><span style="color: #F97583">=></span><span style="color: #E1E4E8"> {</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// if there's no code then redirect to login</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">code</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> url.searchParams.</span><span style="color: #B392F0">get</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"code"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">if</span><span style="color: #E1E4E8"> (</span><span style="color: #F97583">!</span><span style="color: #E1E4E8">code) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">redirect</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"/login?error=no-code"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// there is a code, try to log in</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">supabase</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">createServerClient</span><span style="color: #E1E4E8">(supabaseUrl, supabaseAnonKey, {</span></span>\n<span class="line"><span style="color: #E1E4E8"> cookies: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">getAll</span><span style="color: #E1E4E8">() {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">parseCookieHeader</span><span style="color: #E1E4E8">(request.headers.</span><span style="color: #B392F0">get</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"cookie"</span><span style="color: #E1E4E8">) </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">""</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">setAll</span><span style="color: #E1E4E8">(</span><span style="color: #FFAB70">cookiesToSet</span><span style="color: #E1E4E8">) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> cookiesToSet.</span><span style="color: #B392F0">forEach</span><span style="color: #E1E4E8">(({ </span><span style="color: #FFAB70">name</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">value</span><span style="color: #E1E4E8">, </span><span style="color: #FFAB70">options</span><span style="color: #E1E4E8"> }) </span><span style="color: #F97583">=></span></span>\n<span class="line"><span style="color: #E1E4E8"> cookies.</span><span style="color: #B392F0">set</span><span style="color: #E1E4E8">(name, value, options)</span></span>\n<span class="line"><span style="color: #E1E4E8"> );</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> });</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> { </span><span style="color: #79B8FF">data</span><span style="color: #E1E4E8">, </span><span style="color: #79B8FF">error</span><span style="color: #E1E4E8"> } </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">await</span><span style="color: #E1E4E8"> supabase.auth.</span><span style="color: #B392F0">signInWithOAuth</span><span style="color: #E1E4E8">({</span></span>\n<span class="line"><span style="color: #E1E4E8"> provider: </span><span style="color: #9ECBFF">"github"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> options: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// must be listed as additional_redirect_urls</span></span>\n<span class="line"><span style="color: #E1E4E8"> redirectTo: </span><span style="color: #9ECBFF">`http://localhost:4321/auth/callback`</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> });</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">if</span><span style="color: #E1E4E8"> (error </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">!</span><span style="color: #E1E4E8">data?.url) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// handle error</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #B392F0">redirect</span><span style="color: #E1E4E8">(data.url);</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>Everything is now wired up for the correct end-to-end flow.</p>","tags":["JavaScript","Supabase","OAuth","Login"],"date_published":"2025-08-27T00:00:00.000Z","date_updated":"2025-08-27T00:00:00.000Z"},{"id":"https://humanwhocodes.com/snippets/2025/08/run-multiple-cloudflare-workers-locally/","url":"https://humanwhocodes.com/snippets/2025/08/run-multiple-cloudflare-workers-locally/","title":"Run multiple Cloudflare workers locally","author":{"name":"Nicholas C. Zakas"},"summary":"Wrangler is made primarily to run one worker at a time. You can also use it to run all of your workers at the same time.","content_text":"\nWhen you're testing an application locally, you ideally want an environment that\nmimics production as much as possible. Especially when you're using multiple\n[Cloudflare workers](https://workers.cloudflare.com/), you'll want to make sure\nyou can run them together for end-to-end testing during development. Without\nthis ability, you either need to run everything in the cloud (problematic when\nyour internet connection is down or slow) and test each worker individually.\n\n[Wrangler](https://developers.cloudflare.com/workers/wrangler/) is capable of\nrunning multiple workers at the same time, like this:\n\n```shell\nnpx wrangler dev -c worker1/wrangler.jsonc -c worker2/wrangler.jsonc\n```\n\nThis is important because workers run together in one dev session share\nresources, including queues, and can communicate with one another. That's key\nfor creating a production-like environment locally.\n\nHowever, Wrangler only starts _one server_ for all workers and there's no way to\nroute between them. After some digging, I found this note in the\n[docs](https://developers.cloudflare.com/workers/wrangler/commands/#dev):\n\n> You can provide multiple configuration files to run multiple Workers in one\n> dev session like this:\n> `wrangler dev -c ./wrangler.toml -c ../other-worker/wrangler.toml`. The first\n> config will be treated as the _primary Worker_, which will be exposed over\n> HTTP. The remaining config files will only be accessible via a service binding\n> from the primary Worker.\n\nThat means we need the first worker listed to both list other workers as service\nbindings and route requests to the correct worker.\n\n## The `http` worker\n\nYou can create a simple worker, that I name `http`, to handle this for you. The\nfirst step is to list your other services in the `wrangler.jsonc` file:\n\n```jsonc\n{\n \"$schema\": \"node_modules/wrangler/config-schema.json\",\n \"name\": \"http\",\n \"main\": \"src/index.ts\",\n \"compatibility_date\": \"2025-08-22\",\n \"services\": [\n {\n \"binding\": \"worker1\",\n \"service\": \"worker1\"\n },\n {\n \"binding\": \"worker2\",\n \"service\": \"worker2\"\n }\n ]\n}\n```\n\nNext, you'll use [Hono](https://hono.dev) to route requests based on the request\npath. To make things easy, the path will be the worker binding name, which means\nyou'll only need to update the `wrangler.jsonc` file when you want to add or\nremove workers. Here's the code:\n\n```typescript\nimport { Hono } from \"hono\";\n\ninterface Bindings {\n [binding: string]: Fetcher;\n}\n\nconst app = new Hono<{ Bindings: Bindings }>();\n\napp.all(\"/:worker/*\", (c) => {\n const worker = c.req.param(\"worker\");\n const binding = c.env[worker];\n\n if (!binding || typeof binding.fetch !== \"function\") {\n return c.text(`Worker binding '${worker}' not found`, 404);\n }\n\n // Rewrite the URL to remove the worker prefix\n const url = URL.parse(c.req.url) as URL;\n url.pathname = url.pathname.slice(`/${worker}`.length) || \"/\";\n\n // create a new request object to avoid issues with reused requests\n const request = new Request(url, c.req.raw.clone());\n\n return binding.fetch(request);\n});\n\nexport default app;\n```\n\nNote that you need to pass `c.req.raw` to the worker rather than `c.req`, which\nis a Hono-specific object. In this way, all of the request information is passed\ndirectly to the worker. (You can, optionally, modify it as necessary.)\n\nNow, make sure that the `http` worker is the first one passed to Wrangler:\n\n```shell\nnpx wrangler dev -c http/wrangler.jsonc -c worker1/wrangler.jsonc -c worker2/wrangler.jsonc\n```\n\nThen you can test out your workers locally:\n\n```shell\n# call worker1\ncurl -i -X POST http://localhost:8787/worker1 \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"Hello worker1!\"}'\n\n# call worker2\ncurl -i -X POST http://localhost:8787/worker2 \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"Hello worker2!\"}'\n```\n\nEnjoy your local multi-worker development environment!\n\n**Updated (2025-08-25):** Cleaned up TypeScript code to match best practices for\nHono.\n\n**Updated (2025-09-08):** Enhanced the Hono app so that it handles URL rewriting\nand all HTTP verbs.\n","content_html":"<p>When you’re testing an application locally, you ideally want an environment that\nmimics production as much as possible. Especially when you’re using multiple\n<a href="https://workers.cloudflare.com/">Cloudflare workers</a>, you’ll want to make sure\nyou can run them together for end-to-end testing during development. Without\nthis ability, you either need to run everything in the cloud (problematic when\nyour internet connection is down or slow) and test each worker individually.</p>\n<p><a href="https://developers.cloudflare.com/workers/wrangler/">Wrangler</a> is capable of\nrunning multiple workers at the same time, like this:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">wrangler</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">dev</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-c</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">worker1/wrangler.jsonc</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-c</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">worker2/wrangler.jsonc</span></span></code></pre>\n<p>This is important because workers run together in one dev session share\nresources, including queues, and can communicate with one another. That’s key\nfor creating a production-like environment locally.</p>\n<p>However, Wrangler only starts <em>one server</em> for all workers and there’s no way to\nroute between them. After some digging, I found this note in the\n<a href="https://developers.cloudflare.com/workers/wrangler/commands/#dev">docs</a>:</p>\n<blockquote>\n<p>You can provide multiple configuration files to run multiple Workers in one\ndev session like this:\n<code>wrangler dev -c ./wrangler.toml -c ../other-worker/wrangler.toml</code>. The first\nconfig will be treated as the <em>primary Worker</em>, which will be exposed over\nHTTP. The remaining config files will only be accessible via a service binding\nfrom the primary Worker.</p>\n</blockquote>\n<p>That means we need the first worker listed to both list other workers as service\nbindings and route requests to the correct worker.</p>\n<h2 id="the-http-worker">The <code>http</code> worker</h2>\n<p>You can create a simple worker, that I name <code>http</code>, to handle this for you. The\nfirst step is to list your other services in the <code>wrangler.jsonc</code> file:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">{</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"$schema"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"node_modules/wrangler/config-schema.json"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"name"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"http"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"main"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"src/index.ts"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"compatibility_date"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"2025-08-22"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"services"</span><span style="color: #E1E4E8">: [</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"binding"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"worker1"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"service"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"worker1"</span></span>\n<span class="line"><span style="color: #E1E4E8"> },</span></span>\n<span class="line"><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"binding"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"worker2"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"service"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"worker2"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> ]</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>Next, you’ll use <a href="https://hono.dev">Hono</a> to route requests based on the request\npath. To make things easy, the path will be the worker binding name, which means\nyou’ll only need to update the <code>wrangler.jsonc</code> file when you want to add or\nremove workers. Here’s the code:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #F97583">import</span><span style="color: #E1E4E8"> { Hono } </span><span style="color: #F97583">from</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"hono"</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">interface</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Bindings</span><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> [</span><span style="color: #FFAB70">binding</span><span style="color: #F97583">:</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">string</span><span style="color: #E1E4E8">]</span><span style="color: #F97583">:</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Fetcher</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">app</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">new</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Hono</span><span style="color: #E1E4E8">&#x3C;{ </span><span style="color: #FFAB70">Bindings</span><span style="color: #F97583">:</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Bindings</span><span style="color: #E1E4E8"> }>();</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8">app.</span><span style="color: #B392F0">all</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"/:worker/*"</span><span style="color: #E1E4E8">, (</span><span style="color: #FFAB70">c</span><span style="color: #E1E4E8">) </span><span style="color: #F97583">=></span><span style="color: #E1E4E8"> {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">worker</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> c.req.</span><span style="color: #B392F0">param</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">"worker"</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">binding</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> c.env[worker];</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">if</span><span style="color: #E1E4E8"> (</span><span style="color: #F97583">!</span><span style="color: #E1E4E8">binding </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">typeof</span><span style="color: #E1E4E8"> binding.fetch </span><span style="color: #F97583">!==</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"function"</span><span style="color: #E1E4E8">) {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> c.</span><span style="color: #B392F0">text</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">`Worker binding '${</span><span style="color: #E1E4E8">worker</span><span style="color: #9ECBFF">}' not found`</span><span style="color: #E1E4E8">, </span><span style="color: #79B8FF">404</span><span style="color: #E1E4E8">);</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// Rewrite the URL to remove the worker prefix</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">url</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">URL</span><span style="color: #E1E4E8">.</span><span style="color: #B392F0">parse</span><span style="color: #E1E4E8">(c.req.url) </span><span style="color: #F97583">as</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">URL</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"><span style="color: #E1E4E8"> url.pathname </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> url.pathname.</span><span style="color: #B392F0">slice</span><span style="color: #E1E4E8">(</span><span style="color: #9ECBFF">`/${</span><span style="color: #E1E4E8">worker</span><span style="color: #9ECBFF">}`</span><span style="color: #E1E4E8">.</span><span style="color: #79B8FF">length</span><span style="color: #E1E4E8">) </span><span style="color: #F97583">||</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"/"</span><span style="color: #E1E4E8">;</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #6A737D">// create a new request object to avoid issues with reused requests</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">const</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">request</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">=</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">new</span><span style="color: #E1E4E8"> </span><span style="color: #B392F0">Request</span><span style="color: #E1E4E8">(url, c.req.raw.</span><span style="color: #B392F0">clone</span><span style="color: #E1E4E8">());</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #F97583">return</span><span style="color: #E1E4E8"> binding.</span><span style="color: #B392F0">fetch</span><span style="color: #E1E4E8">(request);</span></span>\n<span class="line"><span style="color: #E1E4E8">});</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #F97583">export</span><span style="color: #E1E4E8"> </span><span style="color: #F97583">default</span><span style="color: #E1E4E8"> app;</span></span></code></pre>\n<p>Note that you need to pass <code>c.req.raw</code> to the worker rather than <code>c.req</code>, which\nis a Hono-specific object. In this way, all of the request information is passed\ndirectly to the worker. (You can, optionally, modify it as necessary.)</p>\n<p>Now, make sure that the <code>http</code> worker is the first one passed to Wrangler:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">wrangler</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">dev</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-c</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">http/wrangler.jsonc</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-c</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">worker1/wrangler.jsonc</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-c</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">worker2/wrangler.jsonc</span></span></code></pre>\n<p>Then you can test out your workers locally:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #6A737D"># call worker1</span></span>\n<span class="line"><span style="color: #B392F0">curl</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-i</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-X</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">POST</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">http://localhost:8787/worker1</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">\\</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-H</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"Content-Type: application/json"</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">\\</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-d</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">'{"message":"Hello worker1!"}'</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #6A737D"># call worker2</span></span>\n<span class="line"><span style="color: #B392F0">curl</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-i</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-X</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">POST</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">http://localhost:8787/worker2</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">\\</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-H</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"Content-Type: application/json"</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">\\</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-d</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">'{"message":"Hello worker2!"}'</span></span></code></pre>\n<p>Enjoy your local multi-worker development environment!</p>\n<p><strong>Updated (2025-08-25):</strong> Cleaned up TypeScript code to match best practices for\nHono.</p>\n<p><strong>Updated (2025-09-08):</strong> Enhanced the Hono app so that it handles URL rewriting\nand all HTTP verbs.</p>","tags":["JavaScript","Cloudflare","Edge Workers"],"date_published":"2025-08-22T00:00:00.000Z","date_updated":"2025-08-22T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2025/06/persona-based-approach-ai-assisted-programming/","url":"https://humanwhocodes.com/blog/2025/06/persona-based-approach-ai-assisted-programming/","title":"A persona-based approach to AI-assisted software development","author":{"name":"Nicholas C. Zakas"},"summary":"Discover how breaking AI assistance into specialized personas can help you tackle complex software development tasks more efficiently and with less frustration.","content_text":"\nI’ve spent most of 2025 experimenting with AI-assisted programming, with mixed results. I tried different models, prompt styles, and editors to understand where AI adds value and where it becomes a distraction. Eventually, I developed a process for using AI to make non-trivial changes.\n\nNon-trivial changes require project knowledge and multiple steps to complete. I wasted too much time trying to rein in models that veered off track and needed a more productive approach. Eventually, I started treating AI as a team of personas rather than a single helper. This let me break the work into chunks and assign tasks to different models based on their strengths.\n\n## The development process\n\nI thought through how I typically implement a feature. The process usually looks like this:\n\n* Gather the requirements\n* Design the solution\n* Implement the solution\n* Test and debug the solution\n\nI assigned a persona to each task:\n\n* The product manager\n* The software architect\n* The implementer\n* The problem solver\n\nAt different steps I felt like I needed some quality control, so I added a couple other personas:\n\n* The tech spec reviewer\n* The implementation reviewer\n\nEach persona plays a role in implementing a feature, and knowing when to use each one has made me more productive. Here’s how I think about them.\n\n## The product manager\n\nThe product manager persona gathers requirements and creates a product requirements document (PRD) focused on functional rather than technical needs. Asking the model to generate user stories helps keep it away from implementation details.\n\n**Prompt:**\n\n> You are a product manager for this application. Your task is to turn user requirements into product requirements documents (PRDs) that include user stories for new features. Add acceptance criteria. If you don’t have enough information, ask me questions about the feature. Insert the design into a Markdown file in the `docs` directory of the repository. The file name should be in Kebab-case named and end with `-prd.md` suffix, for example `docs/saves-data-prd.md`. The file should be formatted in Markdown and include headings and bullet points.\n\nThe application needs an authentication flow to support signed-in functionality. Users should be able to sign up from a link on the login page if they don’t have an account. When signed out, the UI should show a login link; when signed in, it should show the user’s profile picture. The “Recent Saves” section on the homepage and the “Saves” page should be accessible only to logged-in users.\n\n**My choice:** GPT-4.1 \n\n**Rationale:** GPT-4.1 is focused and less likely to go off track. It lacks the deep technical knowledge of Claude or Gemini but does not need it for this role. It’s usually available in standard AI editors, which helps keep costs reasonable. GPT 4.1 isn't considered a premium model so you pay less to use it in most IDEs.\n\n## The architect\n\nThe architect persona designs the technical implementation of the feature. Using the PRD, it creates step-by-step instructions for the change. This persona requires deep technical knowledge and a strong understanding of how systems are built from smaller parts. It does not write code but describes the design to be implemented. You must guide this persona on technical requirements, such as when to use client-side versus server-side logic.\n\n**Prompt:**\n\n > You are a software architect for this application. Your product manager has provided the attached PRD outlining the functional requirements for a new feature. Your task is to design the implementation and ensure all acceptance criteria are met. Scan the current codebase to find integration points. Create a step-by-step guide detailing how to implement your design. Include all details an LLM needs to implement this feature without reading the PRD. DO NOT INCLUDE SOURCE CODE. If anything is unclear, ask me questions about the PRD or implementation. If you need to make assumptions, state them clearly. Insert the design into a Markdown file in the `docs` directory of the repository. The file should be named the same as the PRD without \"prd\" in the name an with \"techspec\" instead. For example, if the PRD is `docs/saves-data-prd.md`, the file should be `docs/saves-data-techspec.md`. The file should be formatted in Markdown and include headings and bullet points.\n\n**My choice:** Gemini 3 Pro, GPT 5.2 (fallback)\n\n**Rationale:** I previously used Gemini 2.5 Pro as the architect but I've switched to GPT-5. I've found GPT-5 to be just as technically knowledgeable and outputs technical specifications with much more depth and specificity. The result is a concrete plan that any LLM can easily follow. GPT-5 is a premium model in VS Code, and it's well worth the extra cost. If you're using an editor where GPT-5 is not available, then Gemini 2.5 Pro is a good second choice.\n\n## The implementer\n\nThe implementer persona carries out the design based on the architect’s technical specification. It needs to follow instructions and not make too many design decisions on its own.\n\n**Prompt:**\n\n> You are a software engineer tasked with implementing the feature described in the attached file. If anything is unclear, ask me questions before starting. You must complete all steps in the document. After finishing, verify that all steps are complete; if not, return and implement the missing steps. Repeat this process until all steps are done.\n\n**My choice:** Claude Haiku 4.5, Gemini 3 Flash (fallback)\n\n**Rationale:** Haiku is a great little model that is fast and effective. It stays on track better than earlier Sonnet models and doesn't get lost when all details aren't provided. On VS Code, it has a 0.33x multiplier, so you can use it without worrying about running out of premium requests. The only downside is it frequently skips reading `AGENTS.md`, but you can make up for that by just asking it do so explicitly first. Gemini 3 Flash, also a 0.33x multiplier, is my next favorite as it's also fast and effective. It seems like its context window gets filled up faster than Haiku, though, which can be a problem for longer implementation plans.\n\n## The problem solver\n\nIdeally, the feature is now implemented. More often, though, something still doesn’t work as expected. That’s when you need the problem solver persona. This persona investigates issues and finds how to fix them. Not all LLMs excel at this, so choosing the right one matters.\n\n**Prompt:**\n\n> The homepage isn’t being updated when I log in. It should show the profile photo in the header and log out button. Fix it.\n\n**My choice:** Gemini 3 Pro\n\n**Rationale:** I've found Gemini 3 Pro to work the best for problems where I have no idea what is going on. It tends to find targeted solutions rather quickly when compared to models like Claude Sonnet 4.5 and GPT 5.2, both of which tend to spend more time and end up with larger edits to address problems. Gemini 3 Pro always just seems to know what to do and what not to do, and overall saves me a lot of time.\n\n## The tech spec reviewer\n\nThe tech spec reviewer persona is quality assurance for the technical specification. While I don't use this persona all the time, I use it whenever the specification is more complex than usual. In that case, I want another review to make sure nothing is missing and there aren't any non-obvious technical issues such as race conditions.\n\n**Prompt:**\n\n> You are a software architect. Critique this specification, paying particular attention to scalability and performance issues. Identify edge cases that are not adequately addressed and possible race conditions. Compare the specification against the PRD to ensure that acceptance criteria is met. \n\n**My choice:** Gemini 3 Pro\n\n**Rationale:** Gemini really shines in this type of role. Its deep technical knowledge is coupled with an ability to describe exact situations where a technical design will fail or introduce problems. Gemini debates approaches using scenarios and explains its thinking well, so you can identify any logic errors or misalignment. Iterating on a specification with Gemini has been a lot of fun for me, personally, as it almost always seems to be correct (provided I gave it the correct requirements). Plus, it is the least sycophantic model I've used, standing its ground on points it knows to be correct.\n\n## The implementation reviewer\n\nThe implementation reviewer persona is quality assurance for the code generated from the technical specification. This is another persona I don't use all the time but lean on for more complex implementations. \n\n**Prompt:**\n\n> You are a software architect. Review the attached specification and then scan the codebase to validate that the specification has been implemented correctly. If there are any problems, list them out in descending order of severity with a proposed fix. Do not implement the fixes, just describe them.\n\n**My choice:** Gemini 3 Pro\n\n**Rationale:** Once again, Gemini is perfect for this role. It's capable of deeply understanding the technical specification and matching it against the existing code. In a recent complex feature, I was surprised at how many problems Gemini found in the implementation even after I had reviewed it. \n\n## Conclusion\n\nOver the past months, I’ve found that treating AI not as a single assistant but as a team of specialized personas dramatically improves my productivity when handling complex changes. By clearly defining roles such as product manager, architect, implementer, problem solver, tech spec reviewer, and implementation reviewer, and choosing the right model for each, I can guide the process efficiently from requirements to debugging. This approach minimizes distractions and leverages each model’s strengths, making AI-assisted programming a practical and powerful part of my workflow. If you’re experimenting with AI in development, I encourage you to try this persona-driven process and see how it transforms your projects.\n\n**Update (2025-08-14):** Switched architect and problem solver personas to use GPT-5. Added the tech spec reviewer and implementation reviewer personas.\n\n**Update (2026-01-28):** Switched architect role, problem solver, tech spec reviewer, and implementation reviewer to Gemini 3 Pro. Switched implementer role to Claude 4.5 Haiku.\n","content_html":"<p>I’ve spent most of 2025 experimenting with AI-assisted programming, with mixed results. I tried different models, prompt styles, and editors to understand where AI adds value and where it becomes a distraction. Eventually, I developed a process for using AI to make non-trivial changes.</p>\n<p>Non-trivial changes require project knowledge and multiple steps to complete. I wasted too much time trying to rein in models that veered off track and needed a more productive approach. Eventually, I started treating AI as a team of personas rather than a single helper. This let me break the work into chunks and assign tasks to different models based on their strengths.</p>\n<h2 id="the-development-process">The development process</h2>\n<p>I thought through how I typically implement a feature. The process usually looks like this:</p>\n<ul>\n<li>Gather the requirements</li>\n<li>Design the solution</li>\n<li>Implement the solution</li>\n<li>Test and debug the solution</li>\n</ul>\n<p>I assigned a persona to each task:</p>\n<ul>\n<li>The product manager</li>\n<li>The software architect</li>\n<li>The implementer</li>\n<li>The problem solver</li>\n</ul>\n<p>At different steps I felt like I needed some quality control, so I added a couple other personas:</p>\n<ul>\n<li>The tech spec reviewer</li>\n<li>The implementation reviewer</li>\n</ul>\n<p>Each persona plays a role in implementing a feature, and knowing when to use each one has made me more productive. Here’s how I think about them.</p>\n<h2 id="the-product-manager">The product manager</h2>\n<p>The product manager persona gathers requirements and creates a product requirements document (PRD) focused on functional rather than technical needs. Asking the model to generate user stories helps keep it away from implementation details.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>You are a product manager for this application. Your task is to turn user requirements into product requirements documents (PRDs) that include user stories for new features. Add acceptance criteria. If you don’t have enough information, ask me questions about the feature. Insert the design into a Markdown file in the <code>docs</code> directory of the repository. The file name should be in Kebab-case named and end with <code>-prd.md</code> suffix, for example <code>docs/saves-data-prd.md</code>. The file should be formatted in Markdown and include headings and bullet points.</p>\n</blockquote>\n<p>The application needs an authentication flow to support signed-in functionality. Users should be able to sign up from a link on the login page if they don’t have an account. When signed out, the UI should show a login link; when signed in, it should show the user’s profile picture. The “Recent Saves” section on the homepage and the “Saves” page should be accessible only to logged-in users.</p>\n<p><strong>My choice:</strong> GPT-4.1</p>\n<p><strong>Rationale:</strong> GPT-4.1 is focused and less likely to go off track. It lacks the deep technical knowledge of Claude or Gemini but does not need it for this role. It’s usually available in standard AI editors, which helps keep costs reasonable. GPT 4.1 isn’t considered a premium model so you pay less to use it in most IDEs.</p>\n<h2 id="the-architect">The architect</h2>\n<p>The architect persona designs the technical implementation of the feature. Using the PRD, it creates step-by-step instructions for the change. This persona requires deep technical knowledge and a strong understanding of how systems are built from smaller parts. It does not write code but describes the design to be implemented. You must guide this persona on technical requirements, such as when to use client-side versus server-side logic.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>You are a software architect for this application. Your product manager has provided the attached PRD outlining the functional requirements for a new feature. Your task is to design the implementation and ensure all acceptance criteria are met. Scan the current codebase to find integration points. Create a step-by-step guide detailing how to implement your design. Include all details an LLM needs to implement this feature without reading the PRD. DO NOT INCLUDE SOURCE CODE. If anything is unclear, ask me questions about the PRD or implementation. If you need to make assumptions, state them clearly. Insert the design into a Markdown file in the <code>docs</code> directory of the repository. The file should be named the same as the PRD without “prd” in the name an with “techspec” instead. For example, if the PRD is <code>docs/saves-data-prd.md</code>, the file should be <code>docs/saves-data-techspec.md</code>. The file should be formatted in Markdown and include headings and bullet points.</p>\n</blockquote>\n<p><strong>My choice:</strong> Gemini 3 Pro, GPT 5.2 (fallback)</p>\n<p><strong>Rationale:</strong> I previously used Gemini 2.5 Pro as the architect but I’ve switched to GPT-5. I’ve found GPT-5 to be just as technically knowledgeable and outputs technical specifications with much more depth and specificity. The result is a concrete plan that any LLM can easily follow. GPT-5 is a premium model in VS Code, and it’s well worth the extra cost. If you’re using an editor where GPT-5 is not available, then Gemini 2.5 Pro is a good second choice.</p>\n<h2 id="the-implementer">The implementer</h2>\n<p>The implementer persona carries out the design based on the architect’s technical specification. It needs to follow instructions and not make too many design decisions on its own.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>You are a software engineer tasked with implementing the feature described in the attached file. If anything is unclear, ask me questions before starting. You must complete all steps in the document. After finishing, verify that all steps are complete; if not, return and implement the missing steps. Repeat this process until all steps are done.</p>\n</blockquote>\n<p><strong>My choice:</strong> Claude Haiku 4.5, Gemini 3 Flash (fallback)</p>\n<p><strong>Rationale:</strong> Haiku is a great little model that is fast and effective. It stays on track better than earlier Sonnet models and doesn’t get lost when all details aren’t provided. On VS Code, it has a 0.33x multiplier, so you can use it without worrying about running out of premium requests. The only downside is it frequently skips reading <code>AGENTS.md</code>, but you can make up for that by just asking it do so explicitly first. Gemini 3 Flash, also a 0.33x multiplier, is my next favorite as it’s also fast and effective. It seems like its context window gets filled up faster than Haiku, though, which can be a problem for longer implementation plans.</p>\n<h2 id="the-problem-solver">The problem solver</h2>\n<p>Ideally, the feature is now implemented. More often, though, something still doesn’t work as expected. That’s when you need the problem solver persona. This persona investigates issues and finds how to fix them. Not all LLMs excel at this, so choosing the right one matters.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>The homepage isn’t being updated when I log in. It should show the profile photo in the header and log out button. Fix it.</p>\n</blockquote>\n<p><strong>My choice:</strong> Gemini 3 Pro</p>\n<p><strong>Rationale:</strong> I’ve found Gemini 3 Pro to work the best for problems where I have no idea what is going on. It tends to find targeted solutions rather quickly when compared to models like Claude Sonnet 4.5 and GPT 5.2, both of which tend to spend more time and end up with larger edits to address problems. Gemini 3 Pro always just seems to know what to do and what not to do, and overall saves me a lot of time.</p>\n<h2 id="the-tech-spec-reviewer">The tech spec reviewer</h2>\n<p>The tech spec reviewer persona is quality assurance for the technical specification. While I don’t use this persona all the time, I use it whenever the specification is more complex than usual. In that case, I want another review to make sure nothing is missing and there aren’t any non-obvious technical issues such as race conditions.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>You are a software architect. Critique this specification, paying particular attention to scalability and performance issues. Identify edge cases that are not adequately addressed and possible race conditions. Compare the specification against the PRD to ensure that acceptance criteria is met.</p>\n</blockquote>\n<p><strong>My choice:</strong> Gemini 3 Pro</p>\n<p><strong>Rationale:</strong> Gemini really shines in this type of role. Its deep technical knowledge is coupled with an ability to describe exact situations where a technical design will fail or introduce problems. Gemini debates approaches using scenarios and explains its thinking well, so you can identify any logic errors or misalignment. Iterating on a specification with Gemini has been a lot of fun for me, personally, as it almost always seems to be correct (provided I gave it the correct requirements). Plus, it is the least sycophantic model I’ve used, standing its ground on points it knows to be correct.</p>\n<h2 id="the-implementation-reviewer">The implementation reviewer</h2>\n<p>The implementation reviewer persona is quality assurance for the code generated from the technical specification. This is another persona I don’t use all the time but lean on for more complex implementations.</p>\n<p><strong>Prompt:</strong></p>\n<blockquote>\n<p>You are a software architect. Review the attached specification and then scan the codebase to validate that the specification has been implemented correctly. If there are any problems, list them out in descending order of severity with a proposed fix. Do not implement the fixes, just describe them.</p>\n</blockquote>\n<p><strong>My choice:</strong> Gemini 3 Pro</p>\n<p><strong>Rationale:</strong> Once again, Gemini is perfect for this role. It’s capable of deeply understanding the technical specification and matching it against the existing code. In a recent complex feature, I was surprised at how many problems Gemini found in the implementation even after I had reviewed it.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>Over the past months, I’ve found that treating AI not as a single assistant but as a team of specialized personas dramatically improves my productivity when handling complex changes. By clearly defining roles such as product manager, architect, implementer, problem solver, tech spec reviewer, and implementation reviewer, and choosing the right model for each, I can guide the process efficiently from requirements to debugging. This approach minimizes distractions and leverages each model’s strengths, making AI-assisted programming a practical and powerful part of my workflow. If you’re experimenting with AI in development, I encourage you to try this persona-driven process and see how it transforms your projects.</p>\n<p><strong>Update (2025-08-14):</strong> Switched architect and problem solver personas to use GPT-5. Added the tech spec reviewer and implementation reviewer personas.</p>\n<p><strong>Update (2026-01-28):</strong> Switched architect role, problem solver, tech spec reviewer, and implementation reviewer to Gemini 3 Pro. Switched implementer role to Claude 4.5 Haiku.</p>","tags":["AI","Claude","GPT"],"date_published":"2025-06-11T00:00:00.000Z","date_updated":"2026-01-28T00:00:00.000Z"},{"id":"https://humanwhocodes.com/blog/2025/04/post-social-media-claude-crosspost/","url":"https://humanwhocodes.com/blog/2025/04/post-social-media-claude-crosspost/","title":"Post to social media using Claude Desktop and Crosspost","author":{"name":"Nicholas C. Zakas"},"summary":"Crosspost is a small utility I wrote to post across social media networks. It now includes an MCP server for use with AI agents.","content_text":"\nWe all spend way too much time on social media these days. If you're like me, you also spend time switching between various social media platforms and, as a result, end up copy-pasting the same content in multiple browser tabs. In order to address this problem, I created Crosspost[^1], an npm package that allows you to post across multiple social media platforms using a command line interface. \n\n## Introducing Crosspost\n\nThe Crosspost command line interface lets you submit a message to any number of different social media networks. The message can either be passed directly on the command line or you can pass in a file using the `--file` option. Here's an overview of how it works:\n\n```\nUsage: crosspost [options] [\"Message to post.\"]\n--twitter, -t Post to Twitter.\n--mastodon, -m Post to Mastodon.\n--bluesky, -b Post to Bluesky.\n--linkedin, -l Post to LinkedIn.\n--discord, -d Post to Discord via bot.\n--discord-webhook Post to Discord via webhook.\n--devto Post to dev.to.\n--mcp Start MCP server.\n--file The file to read the message from.\n--image The image file to upload with the message.\n--image-alt Alt text for the image (defaults: filename).\n--help, -h Show this message.\n```\n\nYou can use the CLI via `npx`. Here are some examples:\n\n```shell\n# Post a message to multiple services\nnpx @humanwhocodes/crosspost -t -m -b \"Check out this beach!\"\n\n# Post a message with an image to multiple services\nnpx @humanwhocodes/crosspost -t -m -b --image ./photo.jpg --image-alt \"A beautiful sunset\" \"Check out this beach!\"\n```\n\nThese examples post the message `\"Check out this beach!\"` to Twitter, Mastodon, and Bluesky with an attached image. You can choose to post to any combination by specifying the appropriate command line options.\n\nEach social media platform is represented by a strategy inside of Crosspost, and each strategy requires specific environment variables to work correctly. (Please refer to the Crosspost README[^1] for details on the environment variables.)\n\n## Using with Claude Desktop\n\nInitially, Crosspost was designed for use in continuous integration systems to help announce releases in my open source projects. Eventually, though, I started thinking about how to make Crosspost easier for me to use to quickly post something on social media manually. I wanted something where the environment variables were already baked in and I didn't have to worry about setting them up each time. At first I thought I'd bundle a web application in the package but instead I grew fascinated with the buzz around MCP servers and set out to create one for Crosspost.\n\nYou can start the Crosspost MCP server by using the `--mcp` command. Most of the command line arguments work in the MCP server, aside from `--file`, `--image`, and `--image-alt`. \n\nTo set up Claude Desktop to use Crosspost:\n\n1. Click on File -> Settings.\n1. Select \"Developer\".\n1. Click \"Edit Config\".\n\nThis will create a `claude_desktop_config.json` file. Open it and add the following:\n\n```json\n{\n \"mcpServers\": {\n \"crosspost\": {\n \"command\": \"npx\",\n \"args\": [\"@humanwhocodes/crosspost\", \"-m\", \"-l\", \"--mcp\"],\n \"env\": {\n \"CROSSPOST_DOTENV\": \"/path/to/.env\"\n }\n }\n }\n}\n```\n\nClaude Desktop only has access to the strategies you've enabled in Crosspost. In this example, the Mastodon and LinkedIn strategies are enabled so those are the only ones Claude can post to on your behalf (you can pick the strategies you want to use). This example also uses a `.env` file to read in the required environment variables.\n\nOnce the `claude_desktop_config.json` file is updated, you need to restart Claude Desktop. Note that just closing the window isn't enough because the Claude Desktop process stays active. You need to click File -> Exit before starting Claude Desktop again.\n\nAt this point, you should see a hammer icon with a number next to it, indicating how many tools are available through installed MCP servers. \n\n![The Claude Desktop toolbar under message entry showing a hammer icon with the number 5 next to it](/images/posts/2025/claude-tools-button.png)\n\nIf you click on the hammer, you'll see a list of all available tools.\n\n![The Claude Desktop dialog listing all of the available Crosspost tools for posting to social media](/images/posts/2025/claude-available-tools.png)\n\nOnce you've confirmed the Crosspost tools are available, you can ask Claude to post a message for you such as:\n\n> Crosspost this message: \"If you are reading this, it means I successfully got Claude to post to my social media.\"\n\n(You can also ask Claude to post to just one social media platform, such as \"Post this to Bluesky,\" if you don't always wants to post to every platform.)\n\nWhen Claude decides it will use one of the Crosspost tools, it will ask for your permission to do so. You can either allow once or for the lifetime of the chat.\n\n![The Claude Desktop dialog asking you to approve the use of the Crosspost tool either once or for the lifetime of the chat.](/images/posts/2025/claude-allow-tool.png)\n\nOnce you allow use of Crosspost, Claude will post on your behalf and let you know when complete.\n\n![The Claude Desktop chat window showing confirmation that a message has been posted across multiple social media platforms.](/images/posts/2025/claude-crosspost-success.png)\n\nI've found this so convenient that Claude Desktop is now the primary way I post to social media. It's fast and I don't get distracted by reading other content in my feed.\n\n## Conclusion\n\nCrosspost started as a simple utility to help automate social media posts for my open source projects, but it has evolved into something much more useful. By integrating with Claude Desktop through an MCP server, it's become a streamlined way to manage social media posts without getting caught up in the endless scroll of content. Whether you're managing multiple social media accounts or just want a more efficient way to post updates, Crosspost combined with Claude Desktop offers a fun solution.\n\n[^1]: [Crosspost](https://github.com/humanwhocodes/crosspost)\n[^2]: [Claude Desktop](https://claude.ai/download)\n","content_html":"<p>We all spend way too much time on social media these days. If you’re like me, you also spend time switching between various social media platforms and, as a result, end up copy-pasting the same content in multiple browser tabs. In order to address this problem, I created Crosspost<sup><a href="#user-content-fn-1" id="user-content-fnref-1" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup>, an npm package that allows you to post across multiple social media platforms using a command line interface.</p>\n<h2 id="introducing-crosspost">Introducing Crosspost</h2>\n<p>The Crosspost command line interface lets you submit a message to any number of different social media networks. The message can either be passed directly on the command line or you can pass in a file using the <code>--file</code> option. Here’s an overview of how it works:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #e1e4e8">Usage: crosspost [options] ["Message to post."]</span></span>\n<span class="line"><span style="color: #e1e4e8">--twitter, -t Post to Twitter.</span></span>\n<span class="line"><span style="color: #e1e4e8">--mastodon, -m Post to Mastodon.</span></span>\n<span class="line"><span style="color: #e1e4e8">--bluesky, -b Post to Bluesky.</span></span>\n<span class="line"><span style="color: #e1e4e8">--linkedin, -l Post to LinkedIn.</span></span>\n<span class="line"><span style="color: #e1e4e8">--discord, -d Post to Discord via bot.</span></span>\n<span class="line"><span style="color: #e1e4e8">--discord-webhook Post to Discord via webhook.</span></span>\n<span class="line"><span style="color: #e1e4e8">--devto Post to dev.to.</span></span>\n<span class="line"><span style="color: #e1e4e8">--mcp Start MCP server.</span></span>\n<span class="line"><span style="color: #e1e4e8">--file The file to read the message from.</span></span>\n<span class="line"><span style="color: #e1e4e8">--image The image file to upload with the message.</span></span>\n<span class="line"><span style="color: #e1e4e8">--image-alt Alt text for the image (defaults: filename).</span></span>\n<span class="line"><span style="color: #e1e4e8">--help, -h Show this message.</span></span></code></pre>\n<p>You can use the CLI via <code>npx</code>. Here are some examples:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #6A737D"># Post a message to multiple services</span></span>\n<span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">@humanwhocodes/crosspost</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-t</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-m</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-b</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"Check out this beach!"</span></span>\n<span class="line"></span>\n<span class="line"><span style="color: #6A737D"># Post a message with an image to multiple services</span></span>\n<span class="line"><span style="color: #B392F0">npx</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">@humanwhocodes/crosspost</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-t</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-m</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">-b</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">--image</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">./photo.jpg</span><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">--image-alt</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"A beautiful sunset"</span><span style="color: #E1E4E8"> </span><span style="color: #9ECBFF">"Check out this beach!"</span></span></code></pre>\n<p>These examples post the message <code>"Check out this beach!"</code> to Twitter, Mastodon, and Bluesky with an attached image. You can choose to post to any combination by specifying the appropriate command line options.</p>\n<p>Each social media platform is represented by a strategy inside of Crosspost, and each strategy requires specific environment variables to work correctly. (Please refer to the Crosspost README<sup><a href="#user-content-fn-1" id="user-content-fnref-1-2" data-footnote-ref="" aria-describedby="footnote-label">1</a></sup> for details on the environment variables.)</p>\n<h2 id="using-with-claude-desktop">Using with Claude Desktop</h2>\n<p>Initially, Crosspost was designed for use in continuous integration systems to help announce releases in my open source projects. Eventually, though, I started thinking about how to make Crosspost easier for me to use to quickly post something on social media manually. I wanted something where the environment variables were already baked in and I didn’t have to worry about setting them up each time. At first I thought I’d bundle a web application in the package but instead I grew fascinated with the buzz around MCP servers and set out to create one for Crosspost.</p>\n<p>You can start the Crosspost MCP server by using the <code>--mcp</code> command. Most of the command line arguments work in the MCP server, aside from <code>--file</code>, <code>--image</code>, and <code>--image-alt</code>.</p>\n<p>To set up Claude Desktop to use Crosspost:</p>\n<ol>\n<li>Click on File -> Settings.</li>\n<li>Select “Developer”.</li>\n<li>Click “Edit Config”.</li>\n</ol>\n<p>This will create a <code>claude_desktop_config.json</code> file. Open it and add the following:</p>\n<pre is:raw="" class="astro-code github-dark" style="background-color: #24292e; overflow-x: auto;" tabindex="0"><code><span class="line"><span style="color: #E1E4E8">{</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"mcpServers"</span><span style="color: #E1E4E8">: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"crosspost"</span><span style="color: #E1E4E8">: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"command"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"npx"</span><span style="color: #E1E4E8">,</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"args"</span><span style="color: #E1E4E8">: [</span><span style="color: #9ECBFF">"@humanwhocodes/crosspost"</span><span style="color: #E1E4E8">, </span><span style="color: #9ECBFF">"-m"</span><span style="color: #E1E4E8">, </span><span style="color: #9ECBFF">"-l"</span><span style="color: #E1E4E8">, </span><span style="color: #9ECBFF">"--mcp"</span><span style="color: #E1E4E8">],</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"env"</span><span style="color: #E1E4E8">: {</span></span>\n<span class="line"><span style="color: #E1E4E8"> </span><span style="color: #79B8FF">"CROSSPOST_DOTENV"</span><span style="color: #E1E4E8">: </span><span style="color: #9ECBFF">"/path/to/.env"</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8"> }</span></span>\n<span class="line"><span style="color: #E1E4E8">}</span></span></code></pre>\n<p>Claude Desktop only has access to the strategies you’ve enabled in Crosspost. In this example, the Mastodon and LinkedIn strategies are enabled so those are the only ones Claude can post to on your behalf (you can pick the strategies you want to use). This example also uses a <code>.env</code> file to read in the required environment variables.</p>\n<p>Once the <code>claude_desktop_config.json</code> file is updated, you need to restart Claude Desktop. Note that just closing the window isn’t enough because the Claude Desktop process stays active. You need to click File -> Exit before starting Claude Desktop again.</p>\n<p>At this point, you should see a hammer icon with a number next to it, indicating how many tools are available through installed MCP servers.</p>\n<p><img src="/images/posts/2025/claude-tools-button.png" alt="The Claude Desktop toolbar under message entry showing a hammer icon with the number 5 next to it"></p>\n<p>If you click on the hammer, you’ll see a list of all available tools.</p>\n<p><img src="/images/posts/2025/claude-available-tools.png" alt="The Claude Desktop dialog listing all of the available Crosspost tools for posting to social media"></p>\n<p>Once you’ve confirmed the Crosspost tools are available, you can ask Claude to post a message for you such as:</p>\n<blockquote>\n<p>Crosspost this message: “If you are reading this, it means I successfully got Claude to post to my social media.”</p>\n</blockquote>\n<p>(You can also ask Claude to post to just one social media platform, such as “Post this to Bluesky,” if you don’t always wants to post to every platform.)</p>\n<p>When Claude decides it will use one of the Crosspost tools, it will ask for your permission to do so. You can either allow once or for the lifetime of the chat.</p>\n<p><img src="/images/posts/2025/claude-allow-tool.png" alt="The Claude Desktop dialog asking you to approve the use of the Crosspost tool either once or for the lifetime of the chat."></p>\n<p>Once you allow use of Crosspost, Claude will post on your behalf and let you know when complete.</p>\n<p><img src="/images/posts/2025/claude-crosspost-success.png" alt="The Claude Desktop chat window showing confirmation that a message has been posted across multiple social media platforms."></p>\n<p>I’ve found this so convenient that Claude Desktop is now the primary way I post to social media. It’s fast and I don’t get distracted by reading other content in my feed.</p>\n<h2 id="conclusion">Conclusion</h2>\n<p>Crosspost started as a simple utility to help automate social media posts for my open source projects, but it has evolved into something much more useful. By integrating with Claude Desktop through an MCP server, it’s become a streamlined way to manage social media posts without getting caught up in the endless scroll of content. Whether you’re managing multiple social media accounts or just want a more efficient way to post updates, Crosspost combined with Claude Desktop offers a fun solution.</p>\n<section data-footnotes="" class="footnotes"><h2 class="sr-only" id="footnote-label">Footnotes</h2>\n<ol>\n<li id="user-content-fn-1">\n<p><a href="https://github.com/humanwhocodes/crosspost">Crosspost</a> <a href="#user-content-fnref-1" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩</a> <a href="#user-content-fnref-1-2" data-footnote-backref="" class="data-footnote-backref" aria-label="Back to content">↩<sup>2</sup></a></p>\n</li>\n</ol>\n</section>","tags":["Open Source","AI","Claude","MCP"],"date_published":"2025-04-08T00:00:00.000Z","date_updated":"2025-04-08T00:00:00.000Z"}]}