<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Tahir Nazir</title>
    <description>The latest articles on DEV Community by Tahir Nazir (@its-tahir).</description>
    <link>https://dev.to/its-tahir</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F2312639%2F58ed0a4e-46e7-4ba0-b8b4-0e3cc10f8153.png</url>
      <title>DEV Community: Tahir Nazir</title>
      <link>https://dev.to/its-tahir</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/its-tahir"/>
    <language>en</language>
    <item>
      <title>Claude's free limit reset: what each reset actually refills (and why /limit-reset says Unknown command)</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Thu, 19 Nov 2026 04:00:02 +0000</pubDate>
      <link>https://dev.to/its-tahir/claudes-free-limit-reset-what-each-reset-actually-refills-and-why-limit-reset-says-unknown-8m8</link>
      <guid>https://dev.to/its-tahir/claudes-free-limit-reset-what-each-reset-actually-refills-and-why-limit-reset-says-unknown-8m8</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Anthropic gave every Pro, Max, Ultra and Team account one free full reset to use before 10 December, on top of the Fable resets. I read the Claude Code builds and Anthropic's help pages to work out what each kind of reset refills, why a Fable reset barely moves your weekly bar, and why Claude Code's hidden /limit-reset command answers 'Unknown command' for most people. Have you spent yours yet, or are you saving it for a heavy week?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A Claude limit reset is a one-time credit from Anthropic that refills your Claude usage limits straight away. Every Pro, Max, Ultra and Team account got one free full reset on 10 November 2026, across all models and limits: use it with "Reset for free" in Settings &amp;gt; Usage before 10 December 2026 at 2:00 PM PT (22:00 UTC).&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;It doesn't move your weekly reset day. Claude Code also has a hidden &lt;code&gt;/limit-reset&lt;/code&gt; command, but it only runs when Anthropic has turned it on for your account; otherwise Claude Code answers &lt;code&gt;Unknown command: /limit-reset&lt;/code&gt;. The button on the web does the same job, because your limits are shared across your account. Without a reset, your weekly limit refills at a fixed day and time shown in Settings &amp;gt; Usage, and your 5-hour limit five hours after your first message.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;th&gt;What to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;"Reset for free" in Settings &amp;gt; Usage&lt;/td&gt;
&lt;td&gt;You hold an unused reset&lt;/td&gt;
&lt;td&gt;Click it when you're actually short of usage (see when to use it)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;Unknown command: /limit-reset&lt;/code&gt; in Claude Code&lt;/td&gt;
&lt;td&gt;The command isn't turned on for your session&lt;/td&gt;
&lt;td&gt;Use Settings &amp;gt; Usage on the web, Desktop or mobile (why)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;/limit-reset to use your {kind} · {left} left · use by {date}&lt;/code&gt;, filled in with your reset, for example "your full reset · 1 left"&lt;/td&gt;
&lt;td&gt;Claude Code is offering a reset you hold&lt;/td&gt;
&lt;td&gt;Run &lt;code&gt;/limit-reset&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your weekly limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your weekly allowance is used up&lt;/td&gt;
&lt;td&gt;A full or weekly reset refills it; otherwise wait for your reset day&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your 5-hour limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your 5-hour window is used up&lt;/td&gt;
&lt;td&gt;Any reset refills it, including a Fable reset&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fable reset used, weekly bar barely moved&lt;/td&gt;
&lt;td&gt;A Fable reset only gives back Fable usage on the weekly limit&lt;/td&gt;
&lt;td&gt;Use the full reset for everything else&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your Fable limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The separate weekly Fable allowance is used up&lt;/td&gt;
&lt;td&gt;A Fable reset gives that usage back&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 17 November 2026, against Claude Code 2.1.325 and Claude's Help Center articles on limit resets, usage limits and the Fable 5.2 launch offers (the Pro and Team standard Fable offer ended on 16 November). The Claude Code strings below are read from the 2.1.323 and 2.1.325 packages themselves. I haven't spent a reset to test them, because a used reset can't be undone; what a reset refills comes from Anthropic's own pages and the Settings &amp;gt; Usage screen shown below, checked on the paid account I use, the same day.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fid730p2optmnhvrtw7z2.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fid730p2optmnhvrtw7z2.png" alt="Claude limit resets: a 5-hour reset refills the 5-hour limit, a weekly reset the weekly limit, a full reset every limit across all models (free one usable until 10 December 2026, 2:00 PM PT), a Fable reset only the weekly usage spent on Fable plus the whole 5-hour limit. None moves the weekly reset day. Use 'Reset for free' in Settings &gt; Usage; in Claude Code, /limit-reset may answer 'Unknown command: /limit-reset'." width="800" height="600"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;What each kind of Claude limit reset refills, and where you can use it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What is a Claude limit reset?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;A limit reset is a credit Anthropic gives to eligible paid plans that puts some or all of your used Claude usage back, immediately, without changing your limits or your reset schedule.&lt;/strong&gt; Claude's Help Center describes it as "given occasionally to eligible plans", and the kind of reset decides what comes back.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Kind&lt;/th&gt;
&lt;th&gt;What it refills&lt;/th&gt;
&lt;th&gt;Where it came from (November 2026)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;5-hour reset&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Your 5-hour limit, back to full&lt;/td&gt;
&lt;td&gt;Offered occasionally&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Weekly reset&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Your weekly limit, back to full&lt;/td&gt;
&lt;td&gt;Offered occasionally&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Full reset&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Every limit, across all models&lt;/td&gt;
&lt;td&gt;One for every Pro, Max, Ultra and Team account, 10 November 2026, use by 10 December, 2:00 PM PT&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Fable reset&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Weekly: only the usage spent on Fable models. 5-hour: the whole window, every model&lt;/td&gt;
&lt;td&gt;Fable 5.2 launch offer, from 9 November 2026&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Fable is Anthropic's newest family of Claude models (Fable 5, Fable 5.1 and Fable 5.2, the last launched 9 November 2026); the Fable reset belongs to its launch offer. These four names are the ones Claude Code itself uses: the 2.1.323 build labels them &lt;code&gt;5-hour reset&lt;/code&gt;, &lt;code&gt;weekly reset&lt;/code&gt;, &lt;code&gt;full reset&lt;/code&gt; and &lt;code&gt;Fable reset&lt;/code&gt;, and &lt;code&gt;/limit-reset&lt;/code&gt; accepts &lt;code&gt;fable&lt;/code&gt;, &lt;code&gt;full&lt;/code&gt;, &lt;code&gt;5-hour&lt;/code&gt; or &lt;code&gt;weekly&lt;/code&gt; as its argument.&lt;/p&gt;

&lt;p&gt;What a reset doesn't do, in the Help Center's words: it doesn't refund extra usage you've already been billed for, it doesn't change your usage credit balance, and "a reset doesn't raise your limits". Once you use one, you can't undo it, and if you downgrade or cancel before using it, it's gone.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I use the free Claude reset before December 10?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;If you're on Pro, Max, Ultra or Team, open Settings &amp;gt; Usage (or clau.de/reset), find Limit resets, click "Reset for free" and confirm, any time before 10 December 2026 at 2:00 PM PT.&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Go to &lt;a href="https://claude.ai/settings/usage" rel="noopener noreferrer"&gt;Settings &amp;gt; Usage&lt;/a&gt; in Claude on the web, Claude Desktop or the Claude mobile app. Anthropic's announcement adds: "You'll find it in Settings &amp;gt; Usage, or at clau.de/reset."&lt;/li&gt;
&lt;li&gt;In the &lt;strong&gt;Limit resets&lt;/strong&gt; section, click &lt;strong&gt;Reset for free&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Confirm with &lt;strong&gt;Reset for free&lt;/strong&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The Help Center adds that "the same 'Reset for free' button appears on the message you see when you reach a limit", and that "an unused reset expires on the day and time listed on the offer". For the free full reset that's 10 December 2026 at 2:00 PM PT (22:00 UTC).&lt;/p&gt;

&lt;p&gt;Here's what that section looked like on the paid account I use, on 13 November 2026, before clicking anything:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhqbxig9peibriz5gxk8y.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhqbxig9peibriz5gxk8y.png" alt="Claude Settings &gt; Usage, Limit resets section, 2 available: Full reset, Expires Dec 11, 3:00 AM GMT+5, with a Reset for free button; Fable reset, Expires Mar 9, 2027, 12:59 PM GMT+5, 'Refills your 5-hour limit and your Fable allowance, and gives back what Fable used on your weekly limit. It doesn't reset your whole week.' with a Reset for free button." width="800" height="258"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Settings &amp;gt; Usage on claude.ai, 13 November 2026: one full reset and one Fable reset, times shown in the viewer's time zone (GMT+5).&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;The expiry times are shown in your own time zone: "Dec 11, 3:00 AM GMT+5" is the same moment as 10 December, 2:00 PM PT, and "Mar 9, 2027, 12:59 PM GMT+5" is the Fable offer's 8 March, 11:59 PM PT. The app describes the Fable reset in one line: "Refills your 5-hour limit and your Fable allowance, and gives back what Fable used on your weekly limit. It doesn't reset your whole week."&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Who got it:&lt;/strong&gt; the announcement names Pro, Max, Ultra and Team. The Free plan has no limit resets, and the Fable launch offer leaves out self-serve and usage-based Enterprise plans and standard seats on legacy seat-based Enterprise plans. If there's no Limit resets section in your Settings &amp;gt; Usage, you don't hold one.&lt;/p&gt;

&lt;p&gt;Anthropic's reason for the giveaway, from the &lt;a href="https://x.com/ClaudeDevs/status/2120275296637321476" rel="noopener noreferrer"&gt;ClaudeDevs announcement&lt;/a&gt;: "We recently fixed a few small issues that used more limits than intended, and the Fable resets didn't do much for those of you who'd already hit your weekly limits for all models." That lines up with the run of GitHub reports in the same weeks: a Team account at 100% of its weekly limit about 30.5 hours after the reset (&lt;a href="https://github.com/anthropics/claude-code/issues/107390" rel="noopener noreferrer"&gt;#107390&lt;/a&gt;), limits draining faster since mid-October while local token counts went down (&lt;a href="https://github.com/anthropics/claude-code/issues/108534" rel="noopener noreferrer"&gt;#108534&lt;/a&gt;), and headless &lt;code&gt;claude -p&lt;/code&gt; runs using limits about 1.8 times faster than interactive ones (&lt;a href="https://github.com/anthropics/claude-code/issues/107134" rel="noopener noreferrer"&gt;#107134&lt;/a&gt;). Those are user reports; Anthropic hasn't said which of them were the issues it fixed.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The usage you restore counts in Claude Code too.&lt;/strong&gt; The Help Center says so directly: "Your usage limits are shared across your Claude account, so the usage a reset restores also applies in Claude Code."&lt;/p&gt;

&lt;h2&gt;
  
  
  Does a Claude limit reset change my weekly reset day?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;No. Every kind of reset leaves your weekly reset day and time exactly where they were.&lt;/strong&gt; The Help Center says "your weekly limits still reset on their usual day and time", and Claude Code's own confirmation reads &lt;code&gt;your weekly reset day stays {week}&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;So a reset is worth the most when there's a lot of week left: used on day 2 of your cycle it buys you nearly a second week, used six hours before your scheduled reset it buys you almost nothing. Settings &amp;gt; Usage shows your next weekly reset, so check it before you click.&lt;/p&gt;

&lt;h2&gt;
  
  
  When should I use my Claude limit reset?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Use it when you've actually run out and your next weekly reset is still days away.&lt;/strong&gt; Because the reset only refills usage and the schedule stays put:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Hit your weekly limit on day 2 of your cycle? A full reset gives you nearly a whole second week before your normal reset.&lt;/li&gt;
&lt;li&gt;Six hours before your weekly reset? Using it then mostly duplicates the refill you were about to get for free.&lt;/li&gt;
&lt;li&gt;On a Pro plan or a Team standard seat, the Fable reset and the included Fable week ended on &lt;strong&gt;16 November 2026 at 11:59 PM PT&lt;/strong&gt;; unused ones didn't carry over. The Fable resets on Max, Ultra and Team premium seats last until &lt;strong&gt;8 March 2027&lt;/strong&gt;, and the free full reset until &lt;strong&gt;10 December 2026, 2:00 PM PT&lt;/strong&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;You don't have to wait until you hit a limit: the Help Center says so, and Claude Code's &lt;code&gt;/limit-reset&lt;/code&gt; will let you, after a question. Its exact wording is &lt;code&gt;You still have {percent}% of your {limit} left — use your {kind} anyway?&lt;/code&gt;, or &lt;code&gt;You haven't reached a limit yet — use your {kind} anyway?&lt;/code&gt; when it doesn't have a number.&lt;/p&gt;

&lt;h2&gt;
  
  
  How many Fable resets do I get, and what do they refill?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;One to three, by how long you've paid, and on the weekly limit they only give back what you spent on Fable models.&lt;/strong&gt; From the &lt;a href="https://support.claude.com/en/articles/17506494-claude-fable-5-2-launch-offers" rel="noopener noreferrer"&gt;Fable 5.2 launch offers&lt;/a&gt; page:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Plan&lt;/th&gt;
&lt;th&gt;Fable resets&lt;/th&gt;
&lt;th&gt;Expire&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Pro, Team standard seat&lt;/td&gt;
&lt;td&gt;One, plus Fable included for one week (up to 50% of your weekly limits)&lt;/td&gt;
&lt;td&gt;16 November 2026, 11:59 PM PT (ended)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Max, Ultra, Team premium seat, legacy seat-based Enterprise premium seat&lt;/td&gt;
&lt;td&gt;One (under 6 months), two (6 to 12 months), three (over 12 months), counted from your first paid bill&lt;/td&gt;
&lt;td&gt;8 March 2027, 11:59 PM PT&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;You only get them if paid billing was in place before 9 November 2026 at 10:00 AM PT. They aren't on the Free plan, self-serve or usage-based Enterprise plans, standard seats on legacy seat-based Enterprise plans, or HIPAA-ready Enterprise plans.&lt;/p&gt;

&lt;p&gt;The Help Center's own example of how a Fable reset works: you've used 80% of your weekly limit, 50% of it on Fable and 30% on other models. After a Fable reset you're back to 30%. That's why people who had already burned their whole week on other models got little from it, and why Anthropic followed up with the full reset. Claude Code describes the same thing in its picker as &lt;code&gt;frees up only what Fable used this week&lt;/code&gt;, and after use it says &lt;code&gt;Fable reset used · what Fable used is back in your weekly limit&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "Refills your 5-hour limit and your Fable allowance" mean?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;It's the description on a Fable reset in Settings &amp;gt; Usage: using it refills your whole 5-hour limit and your separate Fable allowance, and gives back only the part of your weekly limit that Fable models used.&lt;/strong&gt; The full text on the card, shown in the Settings &amp;gt; Usage screenshot above, is "Refills your 5-hour limit and your Fable allowance, and gives back what Fable used on your weekly limit. It doesn't reset your whole week." Claude Code's 2.1.325 build words the same thing as &lt;code&gt;returns what Fable used to your weekly limit&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;So if most of your week went on Opus or Sonnet, a Fable reset gives little back on the weekly bar. The full reset is the one that refills everything.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If the Fable reset card has gone:&lt;/strong&gt; on Pro plans and standard Team seats, both the Fable reset and the included Fable week ended on 16 November 2026 at 11:59 PM PT. The &lt;a href="https://support.claude.com/en/articles/17506494-claude-fable-5-2-launch-offers" rel="noopener noreferrer"&gt;launch offers page&lt;/a&gt; says: "When the week ends, Fable models go back to running on usage credits on Pro plans and standard seats on Team plans." Max, Ultra and premium Team seats keep their Fable resets until 8 March 2027.&lt;/p&gt;

&lt;h2&gt;
  
  
  Can I reset my Claude limit from Claude Code?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Officially no: use "Reset for free" in Settings &amp;gt; Usage on the web, Desktop or mobile, and the refill applies in Claude Code too. Claude Code does also have a hidden &lt;code&gt;/limit-reset&lt;/code&gt; command, switched on per account and never listed in the public changelog.&lt;/strong&gt; It's in all three builds I read (2.1.302, 2.1.322 and 2.1.323), marked hidden so it doesn't appear when you type &lt;code&gt;/&lt;/code&gt;. It only runs if you're signed in with a Claude subscription and Anthropic has enabled it for you.&lt;/p&gt;

&lt;p&gt;There are two versions of it in the code, each behind its own server-side switch:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;What &lt;code&gt;/limit-reset&lt;/code&gt; does&lt;/th&gt;
&lt;th&gt;Its text in 2.1.323&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Older weekly 5-hour reset&lt;/td&gt;
&lt;td&gt;Resets your 5-hour limit once a week; the usage still counts toward your weekly limit&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Reset your 5-hour limit now and keep working; once a week, still counts toward your weekly limit&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Banked resets (current)&lt;/td&gt;
&lt;td&gt;Spends one of the resets you hold: &lt;code&gt;fable&lt;/code&gt;, &lt;code&gt;full&lt;/code&gt;, &lt;code&gt;5-hour&lt;/code&gt; or &lt;code&gt;weekly&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Use an available limit reset and keep working&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;With the current version, a notice at the bottom of Claude Code tells you what you hold, in the form &lt;code&gt;/limit-reset to use your {kind} · {left} left · use by {date}&lt;/code&gt;. Running it with several kinds held asks &lt;code&gt;Which reset do you want to use?&lt;/code&gt;, then &lt;code&gt;Use a {kind}?&lt;/code&gt; with the detail &lt;code&gt;Refills your {limits} now · {returns} · your weekly reset day stays {week}&lt;/code&gt;, and the buttons &lt;code&gt;Yes, use my {kind}&lt;/code&gt; and &lt;code&gt;No, keep it&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The Help Center, meanwhile, says: "The 'Reset for free' button isn't currently available in Claude Code in your terminal or IDE, so use Claude in a browser, on Claude Desktop, or on the mobile apps instead." Both are true at once: the button isn't in Claude Code for most people, and the command exists for the accounts Anthropic has switched it on for. If yours isn't one of them, the web button is the way.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does Claude Code say "Unknown command: /limit-reset"?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Because &lt;code&gt;/limit-reset&lt;/code&gt; isn't enabled in your session, so Claude Code treats it like any command it doesn't know; use "Reset for free" in Settings &amp;gt; Usage instead, since your limits are shared.&lt;/strong&gt; That text comes from Claude Code's own unknown-command handler in the 2.1.323 build, &lt;code&gt;Unknown command: /{name}&lt;/code&gt;, which adds &lt;code&gt;Did you mean /…?&lt;/code&gt; when another command's name is close. The command is registered only when both of these are true:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;You're signed in with a Claude subscription.&lt;/strong&gt; The check requires a claude.ai login. If Claude Code is using an API key, a Console login, Amazon Bedrock, Google Vertex AI or a gateway, the command never exists, and there are no plan resets to spend anyway. Run &lt;code&gt;/status&lt;/code&gt; to see how you're signed in, and see &lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;Claude Code not logged in or login expired&lt;/a&gt; if it's the wrong account.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Anthropic has turned it on for your account.&lt;/strong&gt; Both versions read a server-side switch (&lt;code&gt;enabled: true&lt;/code&gt;). If it's off for you, the command isn't there, whatever plan you're on.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Two more things make it look broken when it isn't:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It never shows up in the &lt;code&gt;/&lt;/code&gt; menu&lt;/strong&gt;, because it's marked hidden. You have to type the whole name.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Turning off telemetry can turn off feature switches.&lt;/strong&gt; &lt;a href="https://github.com/anthropics/claude-code/issues/108726" rel="noopener noreferrer"&gt;#108726&lt;/a&gt; reports that &lt;code&gt;DISABLE_TELEMETRY&lt;/code&gt; hides Fable 5.2 from the &lt;code&gt;/model&lt;/code&gt; picker because feature flags are ignored. &lt;code&gt;/limit-reset&lt;/code&gt; depends on the same kind of switch, so the same setting probably hides it too; I haven't confirmed that for this command.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;On Windows, if you try it headless from Git Bash, quote it carefully: &lt;code&gt;claude -p "/limit-reset"&lt;/code&gt; reached Claude Code on my machine as &lt;code&gt;C:/Program Files/Git/limit-reset&lt;/code&gt;, because Git Bash rewrites arguments that start with &lt;code&gt;/&lt;/code&gt; into Windows paths. Use &lt;code&gt;MSYS_NO_PATHCONV=1&lt;/code&gt; or &lt;code&gt;//limit-reset&lt;/code&gt;. It's an interactive command anyway, so headless mode isn't where to use it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Fix:&lt;/strong&gt; use &lt;strong&gt;Reset for free&lt;/strong&gt; in &lt;a href="https://claude.ai/settings/usage" rel="noopener noreferrer"&gt;Settings &amp;gt; Usage&lt;/a&gt; on the web, Desktop or mobile. Your limits are shared, so Claude Code gets the refill too.&lt;/p&gt;

&lt;h2&gt;
  
  
  What do the /limit-reset messages mean?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Most of them tell you that this reset doesn't cover the limit you're at, or that the server didn't answer.&lt;/strong&gt; The strings, verbatim from Claude Code 2.1.323:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Message&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;/limit-reset · {held} · first expires {date}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The notice when you hold more than one reset, for example &lt;code&gt;2 limit resets&lt;/code&gt;; the date is when the earliest one expires, in your time zone&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Reset used · {resets} left&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;It worked; this is how many you have left&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;A 5-hour limit reset isn't available right now.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Claude Code can't use a 5-hour reset for you at the moment; check Settings &amp;gt; Usage for what you hold&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Your limits are already being reset · one moment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A reset is already in progress; wait instead of running it again&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Couldn't reset your limits with this login · run /login, then try again&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your current sign-in can't spend the reset; sign in again with the account that holds it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;{done} · your weekly reset day stays {week} · {kindResets} left&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;It worked; &lt;code&gt;{done}&lt;/code&gt; is &lt;code&gt;Limits reset&lt;/code&gt;, &lt;code&gt;Weekly limits reset&lt;/code&gt; or &lt;code&gt;5-hour limit reset&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;No {kind} to use&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You don't hold a reset of that kind&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;can't be used while you're at another limit it doesn't refill&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;For example, a Fable reset while you're stuck on the weekly limit for other models&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;doesn't refill the limit you've reached&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Same idea: wrong kind of reset for this limit&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;usable once you reach a limit it refills&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;This reset is set to be used only at a limit&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Couldn't reset your limits · nothing was used · try again in a moment&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The request failed; your reset is untouched&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Couldn't confirm the reset went through · check /usage in a moment · if your limits weren't refilled, run /limit-reset again&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Check &lt;code&gt;/usage&lt;/code&gt; before trying again&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Still couldn't confirm your reset · nothing more was used · if your limits aren't refilled in a few minutes, contact support&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Second failure; contact support if usage doesn't come back&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;{Kind} kept · run /limit-reset at a limit to use it · use by {deadline}&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You chose "No, keep it"&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The older version has its own lines: &lt;code&gt;Weekly reset used · available again {date}&lt;/code&gt;, &lt;code&gt;5-hour limit reset · next reset available {date} · your weekly limit still applies&lt;/code&gt; and &lt;code&gt;Couldn't reset your 5-hour limit right now · try again in a moment&lt;/code&gt;. In 2.1.302 the same lines said "session limit" instead of "5-hour limit"; 2.1.312 renamed it in all limit messages, according to its changelog.&lt;/p&gt;

&lt;h2&gt;
  
  
  When does my Claude weekly limit reset?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;At a fixed day and time assigned to your account, which you can see in Settings &amp;gt; Usage; &lt;code&gt;/usage&lt;/code&gt; shows your plan usage inside Claude Code.&lt;/strong&gt; From Claude's &lt;a href="https://support.claude.com/en/articles/11647753-how-do-usage-and-length-limits-work" rel="noopener noreferrer"&gt;usage limits article&lt;/a&gt;: "Weekly limits reset at a fixed time each week that is assigned to your account," and "your reset day and time stay the same regardless of when you start using Claude or when your subscription begins." The same article notes that "some plans also have a separate weekly limit for Fable."&lt;/p&gt;

&lt;p&gt;The 5-hour limit works differently: "The period starts when you send your first message, and your limit resets in full five hours later." And: "Verified Ultra accounts don't have a five-hour limit."&lt;/p&gt;

&lt;p&gt;In Claude Code, the limit messages name the limit you hit, from this list in the 2.1.323 build: &lt;code&gt;5-hour limit&lt;/code&gt;, &lt;code&gt;weekly limit&lt;/code&gt;, &lt;code&gt;Opus limit&lt;/code&gt;, &lt;code&gt;Sonnet limit&lt;/code&gt;, &lt;code&gt;Fable limit&lt;/code&gt;, &lt;code&gt;usage credit limit&lt;/code&gt;. Each one starts with &lt;code&gt;You've hit your&lt;/code&gt; followed by the limit's name and when it resets.&lt;/p&gt;

&lt;h2&gt;
  
  
  What else can I do when I hit a limit in Claude Code?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Wait for it automatically, switch to a lighter model, or keep going on usage credits.&lt;/strong&gt; None of these needs a reset:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Let Claude Code wait.&lt;/strong&gt; Since 2.1.234 it continues your session by itself when a claude.ai limit resets. Turn it on or off in &lt;code&gt;/config&lt;/code&gt; ("Continue automatically at usage limit"). &lt;code&gt;/rate-limit-options&lt;/code&gt; opens the usage limit menu.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switch to a lighter model.&lt;/strong&gt; On a Pro plan at the weekly limit, the 2.1.323 build suggests &lt;code&gt;try /model opus · more runway&lt;/code&gt; when you're on Fable and &lt;code&gt;try /model sonnet · ~2× runway&lt;/code&gt; when you're on Opus, or &lt;code&gt;try /effort medium&lt;/code&gt; at high effort. If you're unsure which model fits the task, my &lt;a href="https://tools.its-tahir.com/guides/choose-model-for-coding-agents" rel="noopener noreferrer"&gt;model guide for coding agents&lt;/a&gt; compares them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use usage credits.&lt;/strong&gt; In 2.1.323 the limit messages point to &lt;code&gt;/usage-credits&lt;/code&gt; "to keep using Claude Code" or "to request more usage from your admin". With usage credits on, the Help Center says, "your work continues on usage credits instead of stopping."&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use less.&lt;/strong&gt; A common cause of a limit that vanishes fast is a long conversation being resent on every turn. &lt;a href="https://www.its-tahir.com/blog/why-claude-code-uses-so-many-tokens" rel="noopener noreferrer"&gt;Why Claude Code uses so many tokens&lt;/a&gt; covers what eats the allowance and how to cut it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The build also contains a hidden &lt;code&gt;/low-priority&lt;/code&gt; command, "Continue now at lower priority after reaching your 5-hour limit; run again to stop", behind its own switch. Anthropic hasn't announced it, so don't count on having it.&lt;/p&gt;

&lt;p&gt;If the message is a 529 rather than a limit, that's a different problem: capacity, not your quota. See &lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded&lt;/a&gt;. For the exact usage limit wording and fixes in one place, there's also the &lt;a href="https://tools.its-tahir.com/errors/usage-limit-reached" rel="noopener noreferrer"&gt;usage limit reached&lt;/a&gt; error page. Other coding agents have their own versions: &lt;a href="https://www.its-tahir.com/blog/codex-selected-model-is-at-capacity" rel="noopener noreferrer"&gt;Codex's "Selected model is at capacity"&lt;/a&gt; is a capacity error rather than a limit, and &lt;a href="https://www.its-tahir.com/blog/opencode-free-tier-can-only-be-used-from-within-opencode" rel="noopener noreferrer"&gt;OpenCode's "Free usage limit reached"&lt;/a&gt; is its free tier's cap.&lt;/p&gt;

&lt;h2&gt;
  
  
  Claude Code versions that changed limits and resets
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.234&lt;/td&gt;
&lt;td&gt;Continues your session automatically when a claude.ai limit resets ("Continue automatically at usage limit" in &lt;code&gt;/config&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.284&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/rate-limit-options&lt;/code&gt; added to &lt;code&gt;/help&lt;/code&gt; and the command menu for claude.ai subscribers&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.302&lt;/td&gt;
&lt;td&gt;Hidden &lt;code&gt;/limit-reset&lt;/code&gt; present in the build, both versions, with "session limit" wording and no &lt;code&gt;fable&lt;/code&gt;/&lt;code&gt;full&lt;/code&gt;/&lt;code&gt;5-hour&lt;/code&gt;/&lt;code&gt;weekly&lt;/code&gt; argument yet&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.312&lt;/td&gt;
&lt;td&gt;Limit messages say "5-hour limit" instead of "session limit"; VS Code shows reset clock times&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.322&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/limit-reset&lt;/code&gt; accepts &lt;code&gt;fable&lt;/code&gt;, &lt;code&gt;full&lt;/code&gt;, &lt;code&gt;5-hour&lt;/code&gt; or &lt;code&gt;weekly&lt;/code&gt; (present by this build)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.323&lt;/td&gt;
&lt;td&gt;Fixed Fable's weekly limit showing no reset time and no options menu in the terminal; the Fable limit message in &lt;code&gt;-p&lt;/code&gt;, SDK, IDE and cloud sessions now says when it resets&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.325&lt;/td&gt;
&lt;td&gt;Same &lt;code&gt;/limit-reset&lt;/code&gt; text as 2.1.323 (checked in the build); also has &lt;code&gt;/limit-reset · {held} · first expires {date}&lt;/code&gt; and the "already being reset" and "with this login" messages&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The 2.1.302 and 2.1.322 rows come from reading those builds, not from the changelog, which doesn't mention &lt;code&gt;/limit-reset&lt;/code&gt; in any version.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Every Pro, Max, Ultra and Team account got one free full reset on 10 November 2026: every limit, all models, use by 10 December at 2:00 PM PT.&lt;/li&gt;
&lt;li&gt;Use it with 'Reset for free' in Settings &amp;gt; Usage on the web, Desktop or mobile. Limits are shared, so Claude Code gets the refill too.&lt;/li&gt;
&lt;li&gt;No reset moves your weekly reset day, so use one when you've run out with days of the week left, not just before your normal reset.&lt;/li&gt;
&lt;li&gt;A Fable reset gives back only Fable usage on the weekly limit (plus the whole 5-hour limit); the full reset covers everything else.&lt;/li&gt;
&lt;li&gt;Claude Code's /limit-reset is hidden and per account. 'Unknown command: /limit-reset' means it isn't on for you; use the web button.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  Related
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;Claude Code troubleshooting: every error, in one place&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/why-claude-code-uses-so-many-tokens" rel="noopener noreferrer"&gt;Why Claude Code uses so many tokens&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded: retries, and why it isn't your usage limit&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode-classifier-billing" rel="noopener noreferrer"&gt;Claude Code auto mode classifier billing&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;Claude Code not logged in or login expired&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is a Claude limit reset?
&lt;/h3&gt;

&lt;p&gt;A one-time credit that refills your Claude usage limits straight away. Anthropic hands them out occasionally to eligible paid plans. A 5-hour reset refills the 5-hour limit, a weekly reset refills the weekly limit, a full reset refills every limit across all models, and a Fable reset gives back the weekly usage you spent on Fable models and refills the whole 5-hour limit. Use one with the 'Reset for free' button in Settings &amp;gt; Usage.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I use the free Claude reset before December 10?
&lt;/h3&gt;

&lt;p&gt;Open Settings &amp;gt; Usage on claude.ai, in Claude Desktop or in the mobile app (Anthropic also linked clau.de/reset), find the Limit resets section, click 'Reset for free' and confirm. Anthropic gave every Pro, Max, Ultra and Team account one free full reset on 10 November 2026, to use before 10 December 2026 at 2:00 PM PT. The usage it restores applies in Claude Code too, because limits are shared across your account.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does a Claude limit reset change my weekly reset day?
&lt;/h3&gt;

&lt;p&gt;No. Your weekly limit still resets on its usual day and time. A reset only refills usage now, so using it right before your scheduled weekly reset gives you very little, and using it soon after you hit the weekly limit early in the week gives you the most.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I reset my Claude limit from Claude Code?
&lt;/h3&gt;

&lt;p&gt;Officially, no: Claude's Help Center says the 'Reset for free' button isn't available in Claude Code in your terminal or IDE. Claude Code 2.1.323 does contain a hidden /limit-reset command, but it only runs when you're signed in with a Claude subscription and Anthropic has turned it on for your account. Your usage limits are shared, so a reset you use on the web applies in Claude Code straight away.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Claude Code say 'Unknown command: /limit-reset'?
&lt;/h3&gt;

&lt;p&gt;Because the command isn't enabled for your session. In Claude Code 2.1.323, /limit-reset is registered only when you're signed in with a claude.ai subscription and a server-side switch from Anthropic is on for your account. API-key, Console, Amazon Bedrock, Google Vertex AI and gateway sign-ins never get it, and turning off telemetry may hide it too. Use 'Reset for free' in Settings &amp;gt; Usage instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does a Fable reset refill my whole weekly limit?
&lt;/h3&gt;

&lt;p&gt;No. On the weekly limit, a Fable reset gives back only the usage you spent on Fable models; usage on other models stays where it is. It does refill the whole 5-hour limit, including usage on other models. If you've used 80% of your weekly limit, 50% of it on Fable, a Fable reset takes you back to 30%.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I have to hit my limit before using a reset?
&lt;/h3&gt;

&lt;p&gt;No. Claude's Help Center says you don't have to wait until you reach a limit. Claude Code's /limit-reset asks first in that case: it tells you how much of your limit is still left, or that you haven't reached a limit yet, and asks whether to use the reset anyway. Some resets in Claude Code are marked as usable only once you reach a limit they refill.&lt;/p&gt;

&lt;h3&gt;
  
  
  When does my Claude weekly limit reset?
&lt;/h3&gt;

&lt;p&gt;At a fixed day and time assigned to your account, not seven days after you first use Claude. Claude's Help Center says that time stays the same regardless of when you start using Claude or when your subscription began. Settings &amp;gt; Usage shows the next reset, and /usage shows your plan usage in Claude Code. The 5-hour limit starts with your first message and resets in full five hours later.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://support.claude.com/en/articles/17007452-what-is-a-limit-reset" rel="noopener noreferrer"&gt;What is a limit reset? (Claude Help Center)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://support.claude.com/en/articles/17506494-claude-fable-5-2-launch-offers" rel="noopener noreferrer"&gt;Claude Fable 5.2 launch offers (Claude Help Center)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://support.claude.com/en/articles/11647753-how-do-usage-and-length-limits-work" rel="noopener noreferrer"&gt;How do usage and length limits work? (Claude Help Center)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://x.com/ClaudeDevs/status/2120275296637321476" rel="noopener noreferrer"&gt;ClaudeDevs: one free full reset for Pro, Max, Ultra and Team, before December 10 at 2:00 PM PT (X, 10 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (usage limit entries 2.1.234 to 2.1.323)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@anthropic-ai/claude-code-linux-x64/v/2.1.323" rel="noopener noreferrer"&gt;Claude Code 2.1.323 package (@anthropic-ai/claude-code-linux-x64), source of the /limit-reset strings&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/107390" rel="noopener noreferrer"&gt;Team weekly usage reached 100% about 30.5 hours after reset (anthropics/claude-code #107390)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/108534" rel="noopener noreferrer"&gt;Usage limits draining faster since mid-October 2026 (anthropics/claude-code #108534)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/107134" rel="noopener noreferrer"&gt;Headless claude -p drains subscription limits about 1.8x faster (anthropics/claude-code #107134)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/108726" rel="noopener noreferrer"&gt;DISABLE_TELEMETRY hides Fable 5.2 from /model because feature flags are ignored (anthropics/claude-code #108726)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>productivity</category>
      <category>programming</category>
      <category>claude</category>
    </item>
    <item>
      <title>Claude went down twice on 13 November: what broke, what kept working, and what to do next time</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Thu, 19 Nov 2026 03:59:49 +0000</pubDate>
      <link>https://dev.to/its-tahir/claude-went-down-twice-on-13-november-what-broke-what-kept-working-and-what-to-do-next-time-5gll</link>
      <guid>https://dev.to/its-tahir/claude-went-down-twice-on-13-november-what-broke-what-kept-working-and-what-to-do-next-time-5gll</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-ai-outage" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;On 13 November 2026 Claude had two separate outages: a sign-in failure that showed '403 Attention Required! | Cloudflare' mid-session, then a second one that took the API down too. I was in a Claude Code session when the first hit, so I pieced the timeline together from status.claude.com's own incident data. When it happened to you, did an API key keep you working, or were you stuck on the login loop?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude went down twice on 13 November 2026. From 09:58 to 11:58 UTC, signing in to claude.ai and Claude Code failed, often with &lt;code&gt;403 Attention Required! | Cloudflare&lt;/code&gt;, while the Claude API stayed Operational. From 13:09 to 15:38 UTC, a second incident caused errors on claude.ai, the Claude API, Claude Code, Claude Cowork and connectors. Both are resolved, and Anthropic has not published a cause for either.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;If Claude is down for you now, check &lt;a href="https://status.claude.com" rel="noopener noreferrer"&gt;status.claude.com&lt;/a&gt; first; the steps in What should you do when Claude is down? work for any outage. The rest of this page is what happened on 13 November and what each error meant.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 14 November 2026 against status.claude.com, my own Claude Code session during the first incident and reports from Claude Code 2.1.323 users on GitHub and Hacker News. All times are UTC.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu2eaes4p3fnbjxpl1p5u.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fu2eaes4p3fnbjxpl1p5u.png" alt="Claude status page on 13 November 2026: claude.ai Major Outage, Claude Console (platform.claude.com) Partial Outage, Claude API (api.anthropic.com) Operational, Claude Code Partial Outage, Claude Cowork Degraded Performance, Claude for Government Operational, Claude on Cloud Platforms Operational." width="800" height="374"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;status.claude.com on 13 November 2026, during the first (sign-in) incident.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Was Claude down on 13 November 2026? The timeline
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Yes, twice. Anthropic's status page lists two separate incidents on 13 November 2026: a sign-in outage from 09:58 to 11:58 UTC and a wider outage that included the Claude API from 13:09 to 15:38 UTC. A third, older incident affected only the Microsoft 365 connector.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Time (UTC)&lt;/th&gt;
&lt;th&gt;What happened&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;12 Nov, 16:03&lt;/td&gt;
&lt;td&gt;Microsoft 365 connector and Claude for Outlook start failing (Microsoft 365 service incident)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13 Nov, 09:58&lt;/td&gt;
&lt;td&gt;Incident 1 opened: "We are investigating an issue with users authenticating to Claude.ai and Claude Code."&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;about 10:15&lt;/td&gt;
&lt;td&gt;Downdetector shows about 3,800 reports for Claude (&lt;a href="https://www.thesun.co.uk/tech/41012746/claude-ai-crashes-worldwide-microsoft-outage/" rel="noopener noreferrer"&gt;The Sun&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;about 10:40&lt;/td&gt;
&lt;td&gt;Sign-in works again in my own Claude Code session; others report it coming and going&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11:05&lt;/td&gt;
&lt;td&gt;"A fix has been deployed for the issue affecting Claude services and we are monitoring for recovery."&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;11:58&lt;/td&gt;
&lt;td&gt;Incident 1 resolved: "The issue affecting claude.ai and Claude Cowork has been resolved."&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13:09&lt;/td&gt;
&lt;td&gt;Incident 2 opened: degraded performance on claude.ai, the Claude API and Claude Code&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13:52 to 14:03&lt;/td&gt;
&lt;td&gt;Incident 2 widens to connectors (including Claude Docs and Claude Sheets), Claude Security and Claude Managed Agents&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;14:36&lt;/td&gt;
&lt;td&gt;Recovery on claude.ai and the Claude API; connectors still degraded&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;15:33&lt;/td&gt;
&lt;td&gt;Errors back to normal levels; Claude Managed Agents and Claude in Meetings recovering; scheduled tasks and routines running more than two hours late, some skipped; Claude Security scans delayed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;15:38&lt;/td&gt;
&lt;td&gt;Incident 2 resolved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;16:40&lt;/td&gt;
&lt;td&gt;Microsoft 365 connector errors end (resolved on the status page at 21:49)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What Claude services were down on 13 November 2026, and what still worked?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;In the first Claude outage on 13 November 2026, only services behind the claude.ai sign-in failed: claude.ai was in Major Outage, Claude Code and Claude Console (platform.claude.com) in Partial Outage and Claude Cowork degraded, while the Claude API, Claude for Government and Claude on Cloud Platforms stayed Operational. In the second incident the Claude API was affected too.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Service&lt;/th&gt;
&lt;th&gt;Incident 1 (09:58 to 11:58)&lt;/th&gt;
&lt;th&gt;Incident 2 (13:09 to 15:38)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;claude.ai (web, desktop, mobile)&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Major Outage&lt;/strong&gt;, sign-in failing&lt;/td&gt;
&lt;td&gt;Affected, errors&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Code&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Partial Outage&lt;/strong&gt;, subscription sign-in failing&lt;/td&gt;
&lt;td&gt;Affected, including connector use&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Console (platform.claude.com)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Partial Outage&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Not listed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Cowork&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Degraded Performance&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Affected&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude API (api.anthropic.com)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Operational&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Affected&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Connectors (Claude Docs, Claude Sheets)&lt;/td&gt;
&lt;td&gt;Not listed&lt;/td&gt;
&lt;td&gt;Degraded until about 15:33&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude on Cloud Platforms (AWS, Google Cloud, Microsoft Foundry)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Operational&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Not listed&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Which services were down decides what helps: in a sign-in outage, an API key or a cloud provider gets you around it; in an outage that includes the Claude API, an API key does not.&lt;/p&gt;

&lt;h2&gt;
  
  
  What caused the Claude outage on 13 November 2026?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Anthropic has not published a cause for either 13 November 2026 incident. The &lt;a href="https://status.claude.com/incidents/nn11wk485zfn" rel="noopener noreferrer"&gt;first&lt;/a&gt; said it was "investigating an issue with users authenticating to Claude.ai and Claude Code", deployed a fix at 11:05 UTC and resolved it at 11:58. The &lt;a href="https://status.claude.com/incidents/34wq7gxnxvvm" rel="noopener noreferrer"&gt;second&lt;/a&gt;, from 13:09 to 15:38 UTC, was described only as degraded performance. Anthropic has not linked either one to the Microsoft 365 outage.&lt;/strong&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  Was Claude down because of Microsoft?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Not according to Anthropic's status page. It ties the Microsoft 365 outage only to the Microsoft 365 connector and Claude for Outlook, in a &lt;a href="https://status.claude.com/incidents/sqn3fg1l96dl" rel="noopener noreferrer"&gt;separate incident&lt;/a&gt; that ran from 16:03 UTC on 12 November to 16:40 UTC on 13 November, and gives no cause for the two 13 November outages. The one overlap: a Claude login code sent to a Microsoft 365 mailbox may not have arrived.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Anthropic said that incident was "caused by a Microsoft 365 service incident": mail, calendar and search tools in the Microsoft 365 connector failed for many requests, and Claude for Outlook was affected. &lt;a href="https://timesofindia.indiatimes.com/technology/tech-news/microsoft-outage-hits-ai-tools-of-anthropic-and-openai-companies-status-page-give-details/articleshow/135797316.cms" rel="noopener noreferrer"&gt;The Times of India's report&lt;/a&gt; from the same day notes that Claude's API, Claude Code and Console were still listed as operational while it was the only incident.&lt;/p&gt;

&lt;p&gt;Some headlines said Claude went down "due to" the Microsoft outage; Anthropic has not said that, and one developer on &lt;a href="https://news.ycombinator.com/item?id=50480936" rel="noopener noreferrer"&gt;Hacker News&lt;/a&gt; who does no Microsoft Office work at all was logged out of Claude Code the same way. Microsoft's outage could still keep you out of Claude in one way: &lt;strong&gt;if your Claude login code goes to an Outlook or Microsoft 365 work address, it may never arrive.&lt;/strong&gt; A post on &lt;a href="https://www.reddit.com/r/claude/" rel="noopener noreferrer"&gt;r/claude&lt;/a&gt; titled "Microsoft outage means I can't get into Claude" described the same problem. That is your mailbox, not Claude.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Incident&lt;/th&gt;
&lt;th&gt;Time (UTC)&lt;/th&gt;
&lt;th&gt;Affected&lt;/th&gt;
&lt;th&gt;Cause given&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Elevated errors on claude.ai, Claude Code, and platform.claude.com&lt;/td&gt;
&lt;td&gt;13 Nov, 09:58 to 11:58&lt;/td&gt;
&lt;td&gt;claude.ai, Console, Claude Code, Cowork&lt;/td&gt;
&lt;td&gt;None ("an issue with users authenticating")&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Elevated errors on claude.ai, the Claude API, and Claude Code&lt;/td&gt;
&lt;td&gt;13 Nov, 13:09 to 15:38&lt;/td&gt;
&lt;td&gt;claude.ai, Claude API, Claude Code, Cowork, connectors&lt;/td&gt;
&lt;td&gt;None ("degraded performance")&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Elevated errors affecting the Microsoft 365 connector&lt;/td&gt;
&lt;td&gt;12 Nov 16:03 to 13 Nov 16:40&lt;/td&gt;
&lt;td&gt;Microsoft 365 connector, Claude for Outlook&lt;/td&gt;
&lt;td&gt;"a Microsoft 365 service incident"&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  What does "Failed to authenticate. API Error: 403 Attention Required! | Cloudflare" mean in Claude Code?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;In Claude Code, "Failed to authenticate. API Error: 403 Attention Required! | Cloudflare" means a request to Anthropic got Cloudflare's challenge page (HTTP 403) instead of a token or a reply. On 13 November 2026 it was part of Anthropic's sign-in incident, at sign-in and mid-session. When status.claude.com shows everything Operational, a common cause is Cloudflare challenging your network, for example through a VPN, proxy or shared IP.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;This is what Claude Code printed for me on 13 November when it tried to sign in with my claude.ai account:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Failed to authenticate. API Error: 403 Attention Required! | Cloudflare
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuhk88abfqfshaeipb4m1.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fuhk88abfqfshaeipb4m1.png" alt="Claude Code terminal: Failed to authenticate. API Error: 403 Attention Required! | Cloudflare" width="530" height="75"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Claude Code on 13 November 2026, trying to sign in with a claude.ai account during the first incident.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;"Attention Required! | Cloudflare" is the title of Cloudflare's challenge page. Claude Code sent a request to Anthropic and got that page back with HTTP 403 instead of a token or a reply. A command-line tool cannot solve a browser challenge, so it reports the request as an authentication failure.&lt;/p&gt;

&lt;h3&gt;
  
  
  The 403 in the middle of a session
&lt;/h3&gt;

&lt;p&gt;It did not only happen at sign-in. I was in the middle of a task in Claude Code when a session-expired login prompt appeared. I cancelled it and asked it to continue; it worked for a second or two, then the 403 appeared and it asked me to log in again. I then tried Claude Code in the terminal and it was much the same: a few seconds of work, then another error.&lt;/p&gt;

&lt;p&gt;Developers on Claude Code 2.1.323, on macOS, Linux and Windows, reported the same thing on &lt;a href="https://github.com/anthropics/claude-code/issues/109508" rel="noopener noreferrer"&gt;GitHub&lt;/a&gt; and &lt;a href="https://news.ycombinator.com/item?id=50480936" rel="noopener noreferrer"&gt;Hacker News&lt;/a&gt; that morning, from Europe to India and Malaysia, usually in this form:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Please run /login · API Error: 403 Attention Required! | Cloudflare
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What they described, none of which Anthropic has confirmed:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It struck between tool calls.&lt;/strong&gt; One request succeeded, the tool ran locally, and the next request, sending the tool result back, got the 403.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It came and went.&lt;/strong&gt; Sending the message again sometimes worked without a new login; another developer had it work for about ten minutes and then fail again.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cancelling the login prompt bought a few turns.&lt;/strong&gt; &lt;a href="https://news.ycombinator.com/item?id=50480936" rel="noopener noreferrer"&gt;One Hacker News commenter&lt;/a&gt;: "Clicking on cancel in Claude Code will throw you back into the session for another couple of turns." That matches what I saw, though for me each retry lasted only seconds.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Logging in again did not stick.&lt;/strong&gt; Several people got back in, worked for about five minutes, and were kicked out again. Others saw &lt;code&gt;OAuth request failed&lt;/code&gt;, or a login page at claude.com/cai/oauth/authorize that just kept spinning.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It could log you out.&lt;/strong&gt; One developer was signed out twice in a row and had to run &lt;code&gt;/login&lt;/code&gt; each time (&lt;a href="https://github.com/anthropics/claude-code/issues/109515" rel="noopener noreferrer"&gt;#109515&lt;/a&gt;); another said the repeated 403s used up tokens (&lt;a href="https://github.com/anthropics/claude-code/issues/109516" rel="noopener noreferrer"&gt;#109516&lt;/a&gt;).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;For some, it was not their network.&lt;/strong&gt; One report came from a residential connection with no VPN or proxy and reproduced on a second machine. Another found that connecting through a VPN got around it, which suggests (unconfirmed) that the block depended on where the request came from.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If it hits you mid-task, cancel the login prompt and send your message once more; use the turns you get to let the agent finish its current step or note where it got to. If it keeps failing, stop the task rather than letting it retry and spend tokens, and switch to an API key (below) until the incident is resolved.&lt;/p&gt;

&lt;h3&gt;
  
  
  What to do about the 403
&lt;/h3&gt;

&lt;p&gt;It depends on whether an incident is open:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;During a sign-in incident like the first one on 13 November:&lt;/strong&gt; it is most likely part of the incident rather than anything on your machine. Retry once, then wait for the incident to clear or switch to an API key (below).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;When status.claude.com shows everything Operational:&lt;/strong&gt; Cloudflare may be challenging your network. Common triggers are a VPN, a corporate proxy or a shared IP with a poor reputation. Turn the VPN off, try another network (a phone hotspot is the quickest test), then run &lt;code&gt;/login&lt;/code&gt; again.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If the error is "Not logged in · Please run /login" or an OAuth token that expired, that is a different problem with its own fix: see &lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;Claude Code not logged in&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What should you do when Claude is down?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Check status.claude.com to see which components are down, keep any session that still works signed in, and if only the claude.ai sign-in is failing, switch Claude Code to an Anthropic API key, Amazon Bedrock or Google Vertex AI. If the Claude API is down too, an API key will not help; switch tools or wait.&lt;/strong&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  1. Confirm it is not just you
&lt;/h3&gt;

&lt;p&gt;Open &lt;a href="https://status.claude.com" rel="noopener noreferrer"&gt;status.claude.com&lt;/a&gt;. If a component you use is not Operational, it is not your setup. User-report trackers such as Downdetector, StatusGator and &lt;a href="https://uptime.com/claude.ai" rel="noopener noreferrer"&gt;uptime.com&lt;/a&gt; help when the status page has not caught up yet. In Claude Code, &lt;code&gt;/status&lt;/code&gt; shows which account and sign-in method the session uses.&lt;/p&gt;

&lt;h3&gt;
  
  
  2. Stay signed in
&lt;/h3&gt;

&lt;p&gt;In a sign-in outage, a claude.ai tab or Claude Code session that still works has already passed the step that is failing. Logging out to "reset" things puts you back at that step, so leave working sessions alone until the incident is resolved. Staying signed in is not a guarantee: on 13 November some Claude Code users were logged out by the 403 mid-session. But logging out yourself only makes it certain.&lt;/p&gt;

&lt;h3&gt;
  
  
  3. Use Claude Code with an API key, Bedrock or Vertex AI
&lt;/h3&gt;

&lt;p&gt;Claude Code does not need the claude.ai sign-in if you give it another credential. On 13 November this got around the first incident, when the API and Claude on Cloud Platforms stayed Operational; it did not help during the second, when the Claude API was affected too.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Anthropic API key (pay-as-you-go, billed to your Console account, not your Pro/Max plan)&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;ANTHROPIC_API_KEY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;sk-ant-...
claude
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or, if you already pay for a cloud provider, pick one of these (not both):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Amazon Bedrock, with your AWS credentials&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;CLAUDE_CODE_USE_BEDROCK&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;AWS_REGION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-east-1

&lt;span class="c"&gt;# Google Vertex AI, with your Google Cloud credentials&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;CLAUDE_CODE_USE_VERTEX&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;CLOUD_ML_REGION&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;us-east5
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;ANTHROPIC_VERTEX_PROJECT_ID&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;your-project-id
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use a region where your account has Claude models enabled; the &lt;a href="https://code.claude.com/docs/en/amazon-bedrock" rel="noopener noreferrer"&gt;Bedrock&lt;/a&gt; and &lt;a href="https://code.claude.com/docs/en/google-vertex-ai" rel="noopener noreferrer"&gt;Vertex AI&lt;/a&gt; setup pages list the rest.&lt;/p&gt;

&lt;p&gt;On Windows PowerShell, use &lt;code&gt;$env:ANTHROPIC_API_KEY = "sk-ant-..."&lt;/code&gt; instead of &lt;code&gt;export&lt;/code&gt;. Two things to know before you rely on this:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;You need the key already.&lt;/strong&gt; Creating a new key happens in the Console, which was in Partial Outage during the first incident. The time to make a spare key is before the next outage.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;API usage costs money per token.&lt;/strong&gt; It does not draw on your subscription's usage limits. Unset the variable when the incident is over so Claude Code goes back to your plan.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  4. Which Claude Code error is it, and is it an outage?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Not every Claude Code error is an outage. "403 Attention Required! | Cloudflare" and "OAuth request failed" point to a sign-in incident or your network, "API Error: 529" is capacity on one model, and "You've hit your weekly limit" is a usage limit.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;What it is&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;`Failed to authenticate. API Error: 403 Attention Required! \&lt;/td&gt;
&lt;td&gt;Cloudflare`&lt;/td&gt;
&lt;td&gt;Request challenged by Cloudflare (a sign-in incident, or your network)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;`Please run /login · API Error: 403 Attention Required! \&lt;/td&gt;
&lt;td&gt;Cloudflare`&lt;/td&gt;
&lt;td&gt;The same 403 in a running session&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OAuth request failed&lt;/code&gt;, or the claude.com login page spins forever&lt;/td&gt;
&lt;td&gt;Sign-in itself failing during an incident&lt;/td&gt;
&lt;td&gt;Don't keep retrying; use an API key or wait for status.claude.com to show the incident resolved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Not logged in · Please run /login&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your saved login is missing or expired&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/login&lt;/code&gt;; if sign-in itself is down, use an API key until it is back (&lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;details&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;API Error: 529&lt;/code&gt; with an overloaded message&lt;/td&gt;
&lt;td&gt;Capacity on one model, not an outage&lt;/td&gt;
&lt;td&gt;Retry or switch model with &lt;code&gt;/model&lt;/code&gt; (&lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;details&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your weekly limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Usage limit, not an outage&lt;/td&gt;
&lt;td&gt;A &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;limit reset&lt;/a&gt; or wait for your reset time&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For every other Claude Code message, the &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;Claude Code troubleshooting&lt;/a&gt; hub has the full lookup table.&lt;/p&gt;

&lt;h2&gt;
  
  
  What can you use instead of Claude when it is down?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;For chat and writing, use ChatGPT or Google Gemini. For coding in the terminal, use OpenCode, or Claude Code itself with an API key, Amazon Bedrock or Google Vertex AI when only the claude.ai sign-in is down. For work that must not depend on any provider, run a local model through Ollama or LM Studio.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Task&lt;/th&gt;
&lt;th&gt;Alternative&lt;/th&gt;
&lt;th&gt;Note&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Chat and writing&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;ChatGPT&lt;/strong&gt; or &lt;strong&gt;Google Gemini&lt;/strong&gt;
&lt;/td&gt;
&lt;td&gt;At the time of the Times of India report on 13 November, OpenAI's status page listed only its Microsoft 365 connector incident&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Coding agent in the terminal&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Claude Code with an API key, Bedrock or Vertex AI&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Same tool, same project files; works when only the claude.ai sign-in is down&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Another terminal agent&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;OpenCode&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Works with several providers; see &lt;a href="https://www.its-tahir.com/blog/opencode-free-tier-can-only-be-used-from-within-opencode" rel="noopener noreferrer"&gt;OpenCode's free tier&lt;/a&gt; and its limits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Work that must not depend on any provider&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;A local model through Ollama or LM Studio&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Weaker than Claude for large coding tasks, but nothing upstream can take it down&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The &lt;a href="https://www.reddit.com/r/ClaudeAI/comments/1xuzlpu/what_would_you_do_if_theres_a_claude_outage/" rel="noopener noreferrer"&gt;Reddit thread&lt;/a&gt; asking "What would you do if there's a Claude outage?" landed in the same place: several replies said they would switch to ChatGPT, Gemini or a local model for the day.&lt;/p&gt;

&lt;h2&gt;
  
  
  How big was the 13 November outage?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;During the first Claude outage on 13 November 2026, Downdetector showed about 3,800 reports for Claude at 10:15 UTC, according to &lt;a href="https://www.thesun.co.uk/tech/41012746/claude-ai-crashes-worldwide-microsoft-outage/" rel="noopener noreferrer"&gt;The Sun&lt;/a&gt;, falling to around 270 by 10:30. Developers reported the sign-in errors from Austria, Germany, Italy, Poland, India and Malaysia on &lt;a href="https://news.ycombinator.com/item?id=50480936" rel="noopener noreferrer"&gt;Hacker News&lt;/a&gt;.&lt;/strong&gt; Downdetector counts are user reports, not Anthropic figures. The second incident reached further into paid features: scheduled tasks and routines ran more than two hours late, some runs were skipped, and adding a new connector on claude.ai was briefly unavailable.&lt;/p&gt;

&lt;h2&gt;
  
  
  How often does Claude go down?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Short incidents are common and long ones are rare. Selected incidents on status.claude.com from September to November 2026 range from four minutes of overloaded errors on 10 November to the two 13 November outages of about two and two and a half hours, and a 24.5-hour Microsoft 365 connector incident.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Selected recent incidents, in UTC, from status.claude.com:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;Incident&lt;/th&gt;
&lt;th&gt;How long&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;14 Nov 2026&lt;/td&gt;
&lt;td&gt;Elevated errors on purchases, plan upgrades and cancellations on claude.ai (core use not affected)&lt;/td&gt;
&lt;td&gt;About 1.5 hours, 02:34 to 04:03&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13 Nov 2026&lt;/td&gt;
&lt;td&gt;Elevated errors on claude.ai, the Claude API and Claude Code (plus connectors)&lt;/td&gt;
&lt;td&gt;About 2.5 hours, 13:09 to 15:38&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;13 Nov 2026&lt;/td&gt;
&lt;td&gt;Elevated errors on claude.ai, Claude Code and platform.claude.com (sign-in)&lt;/td&gt;
&lt;td&gt;2 hours, 09:58 to 11:58; fix deployed 11:05&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;12 to 13 Nov 2026&lt;/td&gt;
&lt;td&gt;Elevated errors affecting the Microsoft 365 connector (Microsoft 365 service incident)&lt;/td&gt;
&lt;td&gt;About 24.5 hours, 16:03 on 12 Nov to 16:40 on 13 Nov&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10 Nov 2026&lt;/td&gt;
&lt;td&gt;Overloaded errors on Claude Fable 5.2 and Claude Mythos 5.2&lt;/td&gt;
&lt;td&gt;Four minutes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;8 Nov 2026&lt;/td&gt;
&lt;td&gt;Degraded performance for Claude Fable 5.1 (claude.ai, API, Claude Code, Cowork)&lt;/td&gt;
&lt;td&gt;14 minutes, 08:18 to 08:32&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;29 Sep 2026&lt;/td&gt;
&lt;td&gt;Elevated errors on claude.ai, Claude Code, Claude Cowork and the Claude API (also reported by &lt;a href="https://thenextweb.com/news/claude-is-down-anthropic-investigates-outage" rel="noopener noreferrer"&gt;The Next Web&lt;/a&gt;)&lt;/td&gt;
&lt;td&gt;Opened 14:21, resolved 16:27&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;In this list the model incidents were short, the kind a retry gets past. The 13 November incidents were not: a sign-in outage is one a retry does not fix, because the fix is on Anthropic's side.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you keep working through the next Claude outage?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Set up a spare Anthropic API key, Bedrock or Vertex AI credential before an outage, subscribe to status.claude.com updates, avoid a Claude login that depends on a single mailbox, and commit before long Claude Code runs.&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Keep a spare credential ready.&lt;/strong&gt; An Anthropic API key, or Bedrock or Vertex access, set up and tested on a quiet day. During an outage the Console you would create it in may be down too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Subscribe to status updates.&lt;/strong&gt; status.claude.com sends incident updates by email, SMS, Slack, Microsoft Teams or webhook, so you hear about it before you start debugging your own setup.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Don't route your Claude login through a single mailbox you can lose.&lt;/strong&gt; If your work email is on Microsoft 365, the 12 to 13 November outage showed that a mail outage can lock you out of Claude too.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check scheduled work afterwards.&lt;/strong&gt; After the second incident, scheduled tasks and routines ran late and some runs were skipped; rerun anything that matters.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Commit before long runs.&lt;/strong&gt; If access drops mid-task, committed work is safe. Files Claude Code changed with its own tools can be rolled back with &lt;code&gt;/rewind&lt;/code&gt;; see &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;Claude Code deleted my files&lt;/a&gt; for the full recovery steps.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude went down twice on 13 November 2026: a sign-in outage from 09:58 to 11:58 UTC and a wider outage, including the Claude API, from 13:09 to 15:38 UTC. Both were resolved the same day.&lt;/li&gt;
&lt;li&gt;Anthropic has not published a cause for either incident. The Microsoft 365 outage was a separate incident that affected only the Microsoft 365 connector and Claude for Outlook.&lt;/li&gt;
&lt;li&gt;'Failed to authenticate. API Error: 403 Attention Required! | Cloudflare' meant Claude Code got Cloudflare's challenge page instead of a token. During an incident, wait or use an API key; when nothing is down, check your VPN or network.&lt;/li&gt;
&lt;li&gt;The same 403 also hit running sessions as 'Please run /login · API Error: 403 Attention Required! | Cloudflare'. Retry once, then stop the task rather than let it spend tokens.&lt;/li&gt;
&lt;li&gt;An API key, Bedrock or Vertex AI gets Claude Code around a claude.ai sign-in outage, but not an outage that includes the Claude API.&lt;/li&gt;
&lt;li&gt;Check status.claude.com first; only Anthropic can say when an incident is resolved.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;If your terminal shows a capacity error rather than a sign-in failure, &lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded&lt;/a&gt; covers retries and switching models. If you ran out of usage rather than access, &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;Claude limit reset&lt;/a&gt; explains the free full reset that is usable until 10 December 2026. Every other Claude Code error is in the &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;Claude Code troubleshooting&lt;/a&gt; hub.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Is Claude down right now?
&lt;/h3&gt;

&lt;p&gt;Check status.claude.com for the current status; this answer describes 13 November 2026. That day Claude had two separate outages. From 09:58 to 11:58 UTC, signing in to claude.ai and Claude Code failed while the Claude API stayed Operational. From 13:09 to 15:38 UTC, a second incident caused errors on claude.ai, the Claude API, Claude Code, Claude Cowork and connectors such as Claude Docs and Claude Sheets. Both were resolved the same day.&lt;/p&gt;

&lt;h3&gt;
  
  
  What caused the Claude outage on 13 November 2026?
&lt;/h3&gt;

&lt;p&gt;Anthropic has not published a cause for either incident. The first, opened at 09:58 UTC, said: 'We are investigating an issue with users authenticating to Claude.ai and Claude Code.' A fix was deployed at 11:05 UTC and it was resolved at 11:58 UTC. The second, from 13:09 to 15:38 UTC, was described as degraded performance across claude.ai, the Claude API, Claude Code and connectors. A separate Microsoft 365 incident affected only the Microsoft 365 connector and Claude for Outlook.&lt;/p&gt;

&lt;h3&gt;
  
  
  Was Claude down because of the Microsoft outage?
&lt;/h3&gt;

&lt;p&gt;Not according to Anthropic's status page. The Microsoft 365 outage broke the Microsoft 365 connector (mail, calendar and search tools) and Claude for Outlook from 16:03 UTC on 12 November to 16:40 UTC on 13 November. The two 13 November outages on claude.ai, Claude Code and the API were listed as separate incidents with no cause given. The two could overlap for you if your Claude login code goes to an Outlook or Microsoft 365 work address, because that email may not arrive.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does 'Failed to authenticate. API Error: 403 Attention Required! | Cloudflare' mean in Claude Code?
&lt;/h3&gt;

&lt;p&gt;Claude Code's request was answered by a Cloudflare challenge page instead of Anthropic's service, so it never got a token or a reply. On 13 November 2026 it was part of Anthropic's sign-in incident. During an incident, wait for it to resolve or use an API key. Outside an incident, a common cause is Cloudflare challenging your network, for example through a VPN, proxy or shared IP; try another network.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Claude Code say 'Please run /login · API Error: 403 Attention Required! | Cloudflare' in the middle of a session?
&lt;/h3&gt;

&lt;p&gt;On 13 November 2026 developers on Claude Code 2.1.323 reported this 403 in running sessions during Anthropic's sign-in incident: a request sending a tool result back was answered by Cloudflare's challenge page. Cancelling the login prompt and sending the message again usually bought a few more turns, but the error came back and some people were logged out. Retry once; if it repeats, stop the task so it does not keep spending tokens, and use an API key until the incident is resolved.&lt;/p&gt;

&lt;h3&gt;
  
  
  Did the Claude API work during the 13 November outage?
&lt;/h3&gt;

&lt;p&gt;During the first incident, yes: the Claude API at api.anthropic.com and Claude on AWS, Google Cloud and Microsoft Foundry stayed Operational from 09:58 to 11:58 UTC, so API keys and cloud providers got around the failing sign-in. During the second incident, from 13:09 to 15:38 UTC, Anthropic listed the Claude API as affected too, so an API key did not help then.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Claude Code work during a claude.ai outage?
&lt;/h3&gt;

&lt;p&gt;It depends on what is down and how Claude Code signs in. If only the claude.ai sign-in is failing, as in the first 13 November incident, Claude Code with an Anthropic API key, Amazon Bedrock or Google Vertex AI keeps working. If the Claude API is affected too, as in the second incident, an API key does not help, though Bedrock or Vertex AI may, if their components stay Operational. Run /status inside Claude Code to see which sign-in you use.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I log out of Claude during an outage?
&lt;/h3&gt;

&lt;p&gt;No. In a sign-in outage like the one on 13 November, a session that still works is the one thing you have. Logging out to 'fix' it puts you back at the step that is failing. Wait for Anthropic to mark the incident resolved, then sign in again if you need to.&lt;/p&gt;

&lt;h3&gt;
  
  
  What can I use instead of Claude when it is down?
&lt;/h3&gt;

&lt;p&gt;For chat and writing, ChatGPT or Google Gemini. For a coding agent in the terminal, OpenCode, or Claude Code itself with an API key, Bedrock or Vertex AI when only the claude.ai sign-in is down. For work that must not depend on any provider, a local model through Ollama or LM Studio.&lt;/p&gt;

&lt;h3&gt;
  
  
  Where can I track the Claude outage status?
&lt;/h3&gt;

&lt;p&gt;The official source is status.claude.com, where Anthropic posts timestamped updates and a 90-day uptime bar per service. You can subscribe there by email, SMS, Slack, Microsoft Teams or webhook. Downdetector, StatusGator and uptime.com add user reports, which help show whether it is just you.&lt;/p&gt;

&lt;h3&gt;
  
  
  How long did the 13 November 2026 Claude outage last?
&lt;/h3&gt;

&lt;p&gt;There were two outages. The sign-in incident ran from 09:58 to 11:58 UTC, about two hours, with a fix deployed at 11:05. The second incident ran from 13:09 to 15:38 UTC, about two and a half hours. Model incidents earlier that month were much shorter: 14 minutes on 8 November and four minutes on 10 November. The Microsoft 365 connector incident lasted about 24 and a half hours.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://status.claude.com/incidents/nn11wk485zfn" rel="noopener noreferrer"&gt;Claude Status: Elevated errors on claude.ai, Claude Code, and platform.claude.com (13 November 2026, 09:58 to 11:58 UTC)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://status.claude.com/incidents/34wq7gxnxvvm" rel="noopener noreferrer"&gt;Claude Status: Elevated errors on claude.ai, the Claude API, and Claude Code (13 November 2026, 13:09 to 15:38 UTC)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://status.claude.com/incidents/sqn3fg1l96dl" rel="noopener noreferrer"&gt;Claude Status: Elevated errors affecting the Microsoft 365 connector (12 to 13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/109508" rel="noopener noreferrer"&gt;Claude down? (anthropics/claude-code issue #109508, with mid-session 403 reports, 13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/109516" rel="noopener noreferrer"&gt;Mid-session 403 Cloudflare 'Attention Required' auth error burns tokens (anthropics/claude-code issue #109516)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://news.ycombinator.com/item?id=50480936" rel="noopener noreferrer"&gt;Claude OAuth Failures (Hacker News discussion, 13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.thesun.co.uk/tech/41012746/claude-ai-crashes-worldwide-microsoft-outage/" rel="noopener noreferrer"&gt;Claude AI goes down for thousands of users worldwide as Microsoft outage drags into second day (The Sun, 13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://timesofindia.indiatimes.com/technology/tech-news/microsoft-outage-hits-ai-tools-of-anthropic-and-openai-companies-status-page-give-details/articleshow/135797316.cms" rel="noopener noreferrer"&gt;Microsoft outage hits AI tools of Anthropic and OpenAI (Times of India, 13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.reddit.com/r/ClaudeAI/comments/1xuzlpu/what_would_you_do_if_theres_a_claude_outage/" rel="noopener noreferrer"&gt;What would you do if there's a Claude outage? (Reddit r/ClaudeAI)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.reddit.com/r/claude/" rel="noopener noreferrer"&gt;r/claude (Reddit), including 'Microsoft outage means I can't get into Claude' (13 November 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://thenextweb.com/news/claude-is-down-anthropic-investigates-outage" rel="noopener noreferrer"&gt;Claude is down as Anthropic investigates errors across its services (The Next Web, 29 September 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://uptime.com/claude.ai" rel="noopener noreferrer"&gt;Is claude.ai down? (Uptime.com)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-ai-outage" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>news</category>
      <category>claude</category>
    </item>
    <item>
      <title>I dug into Claude Code's 429 error: two messages, and neither is your usage limit</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Wed, 18 Nov 2026 13:48:47 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-dug-into-claude-codes-429-error-two-messages-and-neither-is-your-usage-limit-3gl6</link>
      <guid>https://dev.to/its-tahir/i-dug-into-claude-codes-429-error-two-messages-and-neither-is-your-usage-limit-3gl6</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-error-429" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Claude Code's 'Server is temporarily limiting requests (not your usage limit)' has a 69-comment GitHub thread, including people running agent teams on Max. I read the message strings in the 2.1.325 build and the official error reference to work out what each 429 actually means and what Claude Code already retried before showing it. Have you hit it, and were you running parallel subagents at the time?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Code error 429 means a rate limit refused the request, and Claude Code shows it in two ways. &lt;code&gt;API Error: Server is temporarily limiting requests (not your usage limit)&lt;/code&gt; is a short server-side throttle on a claude.ai subscription or gateway sign-in. &lt;code&gt;API Error: Request rejected (429)&lt;/code&gt; is a 429 on an Anthropic API key, Amazon Bedrock, Google Vertex AI or Microsoft Foundry project, usually that key's rate limit. Neither is your plan's usage limit.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;On Claude Code v2.1.199 or later, a temporary 429 has already been retried up to 10 times (the default) before you see it. The fix depends on which line you have: for the first, wait and run fewer subagents and sessions at once; for the second, check which credential &lt;code&gt;/status&lt;/code&gt; shows and the limits on that key or project.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 15 November 2026 against the Claude Code 2.1.325 build (message strings read from the npm package), the installed Claude Code 2.1.302 on my Windows machine, which contains the same two 429 messages and the same fallback sentence (check below), and the official &lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;error reference&lt;/a&gt;. I have not triggered a real 429 on my own account; the real-world reports below come from GitHub.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk297htjcbx7djp6iv02c.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fk297htjcbx7djp6iv02c.png" alt="Claude Code error 429 messages: API Error: Server is temporarily limiting requests (not your usage limit) for claude.ai subscription or gateway sign-ins, a short server throttle retried up to 10 times; API Error: Request rejected (429) · this may be a temporary capacity issue for API key, Bedrock, Vertex AI or Foundry, that key's rate limit; You've hit your session limit · resets 3:45pm, the plan quota; spend limit reached · resets Dec 1, a gateway spend cap that is not retried." width="800" height="622"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Four messages that can follow an HTTP 429 in Claude Code, and what each one means.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Which Claude Code 429 message do you have?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Claude Code turns an HTTP 429 into different messages depending on how you sign in and what the response carries. A claude.ai subscription or gateway sign-in gets &lt;code&gt;Server is temporarily limiting requests (not your usage limit)&lt;/code&gt; for a throttle and &lt;code&gt;You've hit your session limit&lt;/code&gt; for a real plan limit; an API key or cloud provider gets &lt;code&gt;Request rejected (429)&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;Who sees it&lt;/th&gt;
&lt;th&gt;What it is&lt;/th&gt;
&lt;th&gt;First thing to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;API Error: Server is temporarily limiting requests (not your usage limit)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;claude.ai subscription, or a gateway&lt;/td&gt;
&lt;td&gt;A short server-side throttle, not your quota&lt;/td&gt;
&lt;td&gt;Wait, then run fewer subagents and sessions at once&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Anthropic API key, Amazon Bedrock, Google Vertex AI, Microsoft Foundry&lt;/td&gt;
&lt;td&gt;The rate limit on that key or project&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/status&lt;/code&gt; to confirm the credential, then check its limits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;You've hit your session limit · resets 3:45pm&lt;/code&gt; (also weekly, Opus, Sonnet)&lt;/td&gt;
&lt;td&gt;claude.ai subscription&lt;/td&gt;
&lt;td&gt;Your plan's usage quota&lt;/td&gt;
&lt;td&gt;Wait for the reset, &lt;code&gt;/usage&lt;/code&gt;, usage credits or a &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;limit reset&lt;/a&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your monthly spend limit · raise it at ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Plans with usage credits&lt;/td&gt;
&lt;td&gt;The spend limit on your usage credits&lt;/td&gt;
&lt;td&gt;Raise it in Settings &amp;gt; Usage or wait for the window shown&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;spend limit reached · resets Dec 1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Claude apps gateway&lt;/td&gt;
&lt;td&gt;The gateway operator's spend cap&lt;/td&gt;
&lt;td&gt;Wait for the date or ask the operator; Claude Code does not retry it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;API Error: Request rejected (429) · Too Many Requests&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Anyone behind a proxy or gateway&lt;/td&gt;
&lt;td&gt;A proxy's own 429 page; its title follows the &lt;code&gt;·&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Check that proxy's or gateway's rate limits&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;In the 2.1.325 build the first two lines come from one place: Claude Code checks whether you are signed in with a claude.ai subscription or a gateway, and picks "Server is temporarily limiting requests (not your usage limit)" if you are and "Request rejected (429)" if you are not. After the &lt;code&gt;·&lt;/code&gt; it prints the server's own message, or the "this may be a temporary capacity issue" sentence when there is none. Here "gateway" means Claude Code pointed at an LLM gateway or a Claude apps gateway instead of Anthropic's API directly. That is why developers on GitHub quote extra text such as &lt;code&gt;· Rate limited&lt;/code&gt; or &lt;code&gt;· Type 2b rate limited. Please try again later.&lt;/code&gt; at the end.&lt;/p&gt;

&lt;p&gt;The &lt;a href="https://tools.its-tahir.com/errors/request-rejected-429" rel="noopener noreferrer"&gt;tools site's Request rejected (429) page&lt;/a&gt; has the same message as a quick lookup.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "Server is temporarily limiting requests (not your usage limit)" mean?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;API Error: Server is temporarily limiting requests (not your usage limit)&lt;/code&gt; means the server applied a short-lived throttle that has nothing to do with your plan quota. Claude Code knows it is not your usage limit because the 429 arrives without the quota headers a real plan-limit response carries. Since Claude Code v2.1.199 it is retried automatically before you see it, whichever way you sign in.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;API Error: Server is temporarily limiting requests (not your usage limit)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The words &lt;code&gt;(not your usage limit)&lt;/code&gt; in the message are the important part. If you had run out of your plan, Claude Code would say &lt;code&gt;You've hit your session limit · resets 3:45pm&lt;/code&gt; or &lt;code&gt;You've hit your weekly limit&lt;/code&gt; instead; see &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;Claude limit reset&lt;/a&gt; for those.&lt;/p&gt;

&lt;p&gt;What developers report in the main GitHub issue, &lt;a href="https://github.com/anthropics/claude-code/issues/53915" rel="noopener noreferrer"&gt;#53915&lt;/a&gt; (open since April 2026, 69 comments as of 15 November 2026), none of which Anthropic has confirmed:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It comes with parallel work.&lt;/strong&gt; Two Max subscribers say it starts when they run a team of subagents, one of them with several sessions on different machines at once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;It can last hours.&lt;/strong&gt; The original report describes three hours of it after "just a couple of seconds of use", on Windows 11 in VS Code's integrated terminal; another developer had it "for the whole day".&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switching models or effort did not reliably help.&lt;/strong&gt; Some lowered effort to medium and were still throttled; one suggested switching to a 1M-context model variant, which is not a general fix.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Usage seemed to climb anyway.&lt;/strong&gt; Several people say their usage meter rose while every request failed. Anthropic does not document that a rejected request counts, so treat this as reported, not confirmed, and stop resending in a loop.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Wait a minute and send the message again. On v2.1.199 or later Claude Code has already retried it up to 10 times, so pressing Enter repeatedly only adds requests.&lt;/li&gt;
&lt;li&gt;Cut parallel work: fewer subagents, fewer Claude Code sessions at the same time, especially across machines on the same account.&lt;/li&gt;
&lt;li&gt;Check &lt;a href="https://status.claude.com" rel="noopener noreferrer"&gt;status.claude.com&lt;/a&gt;. During an incident, such as &lt;a href="https://www.its-tahir.com/blog/claude-ai-outage" rel="noopener noreferrer"&gt;the 13 November 2026 outages&lt;/a&gt;, the throttle is not about you.&lt;/li&gt;
&lt;li&gt;For unattended runs, set &lt;code&gt;CLAUDE_CODE_RETRY_WATCHDOG=1&lt;/code&gt; so Claude Code keeps waiting it out instead of failing (below).&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  What does "Request rejected (429)" mean?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;API Error: Request rejected (429)&lt;/code&gt; is how Claude Code shows a 429 when it is not signed in with a claude.ai subscription or a gateway. Usually it is the rate limit on your Anthropic API key, Amazon Bedrock, Google Vertex AI or Microsoft Foundry project; it can also be a temporary capacity throttle or a proxy's own 429. The sentence after the &lt;code&gt;·&lt;/code&gt; names where to check service status for your provider.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The trailing sentence changes with your setup. In the 2.1.325 build it reads "If it persists, check your Amazon Bedrock service status." on Amazon Bedrock, and names Google Vertex AI or Microsoft Foundry the same way on those (the docs call Vertex AI "Google Cloud's Agent Platform"), and with a custom &lt;code&gt;ANTHROPIC_BASE_URL&lt;/code&gt; it names your gateway host. If a proxy or load balancer answered with its own HTML 429 page, the text after the &lt;code&gt;·&lt;/code&gt; is that page's title, usually &lt;code&gt;Too Many Requests&lt;/code&gt;; before v2.1.281 Claude Code printed the whole page.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What to do:&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Run &lt;code&gt;/status&lt;/code&gt; and check the credential.&lt;/strong&gt; The &lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;Claude Code error reference&lt;/a&gt; calls this out first: a stray &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; in your environment can route Claude Code through a low-tier API key instead of your subscription. On Windows, my own habit is to check both the current shell and the user environment variables; on my machine &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; is unset in both. The &lt;a href="https://tools.its-tahir.com/api-key-checker" rel="noopener noreferrer"&gt;API key checker&lt;/a&gt; tells you whether a key is valid.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check the limits on that key or project.&lt;/strong&gt; For Anthropic API keys, the &lt;a href="https://platform.claude.com/docs/en/api/rate-limits" rel="noopener noreferrer"&gt;rate limits page&lt;/a&gt; explains tiers and per-workspace caps; Bedrock and Vertex AI quotas live in the AWS and Google Cloud consoles.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lower concurrency.&lt;/strong&gt; Many parallel subagents multiply requests per minute. For high-volume scripted runs, the docs also suggest switching to a smaller model with &lt;code&gt;/model&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Ask for a higher tier&lt;/strong&gt; if you hit it during normal use.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Is a 429 the same as hitting my usage limit?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;No. A claude.ai plan limit is also delivered as a 429, but it carries quota headers, and Claude Code shows it as &lt;code&gt;You've hit your session limit&lt;/code&gt;, &lt;code&gt;You've hit your weekly limit&lt;/code&gt;, &lt;code&gt;You've hit your Opus limit&lt;/code&gt; or &lt;code&gt;You've hit your Sonnet limit&lt;/code&gt;, each with a reset time. Only those messages mean your plan ran out.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Message&lt;/th&gt;
&lt;th&gt;Plan quota?&lt;/th&gt;
&lt;th&gt;Retried?&lt;/th&gt;
&lt;th&gt;Ends when&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Server is temporarily limiting requests (not your usage limit)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;Yes, up to 10 times&lt;/td&gt;
&lt;td&gt;The throttle lifts, usually soon&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Request rejected (429)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No, the key's or project's rate limit&lt;/td&gt;
&lt;td&gt;Yes, if temporary&lt;/td&gt;
&lt;td&gt;The rate-limit window passes&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your session limit · resets 3:45pm&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Yes&lt;/td&gt;
&lt;td&gt;No, it waits for the reset&lt;/td&gt;
&lt;td&gt;The reset time shown&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You've hit your monthly spend limit&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Spend limit on usage credits&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;You raise it, or the window shown resets&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;spend limit reached · resets Dec 1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Gateway operator's cap&lt;/td&gt;
&lt;td&gt;No (&lt;code&gt;x-should-retry: false&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;00:00 UTC on that date, or the operator raises it&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;If you see a real plan limit, &lt;a href="https://www.its-tahir.com/blog/claude-limit-reset" rel="noopener noreferrer"&gt;Claude limit reset&lt;/a&gt; covers what a reset refills, and the &lt;a href="https://tools.its-tahir.com/errors/usage-limit-reached" rel="noopener noreferrer"&gt;usage limit reached page&lt;/a&gt; on the tools site lists the variants.&lt;/p&gt;

&lt;h2&gt;
  
  
  Does Claude Code retry a 429 automatically?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Yes. Claude Code retries temporary 429 throttles up to 10 times with exponential backoff before showing the error, and while it does, the spinner shows &lt;code&gt;Retrying in Ns · attempt x/y&lt;/code&gt; after a rate-limit label. A gateway's spend-limit 429 is the exception: it is not a throttle and is not retried.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;Since v2.1.199 this includes throttles on a claude.ai subscription; before that, a subscription session failed the turn on the first one, and only API key and Enterprise sign-ins retried. You can change the behaviour with environment variables (full list on the &lt;a href="https://tools.its-tahir.com/claude-code-settings" rel="noopener noreferrer"&gt;Claude Code settings reference&lt;/a&gt;):&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Variable&lt;/th&gt;
&lt;th&gt;Default&lt;/th&gt;
&lt;th&gt;What it does for a 429&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLAUDE_CODE_MAX_RETRIES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;10&lt;/td&gt;
&lt;td&gt;Number of retry attempts. Lower it in scripts to fail faster; capped at 15 unless the watchdog is on&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLAUDE_CODE_RETRY_WATCHDOG&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;unset&lt;/td&gt;
&lt;td&gt;Set to &lt;code&gt;1&lt;/code&gt; for CI and other unattended runs: retries 429 and 529 capacity errors indefinitely. Fails at once when a standard-speed request gets a 429 that reports a spend limit or exhausted usage credits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;unset&lt;/td&gt;
&lt;td&gt;Caps how long each request waits out 429 and 529 errors under the watchdog, for example &lt;code&gt;1800000&lt;/code&gt; for 30 minutes. Requires v2.1.295 or later&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# Unattended run that waits out 429s for up to 30 minutes per request&lt;/span&gt;
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;CLAUDE_CODE_RETRY_WATCHDOG&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
&lt;span class="kd"&gt;export&lt;/span&gt; &lt;span class="nv"&gt;CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1800000
claude -p &lt;span class="s2"&gt;"run the test suite and fix failures"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On Windows PowerShell, use &lt;code&gt;$env:CLAUDE_CODE_RETRY_WATCHDOG = "1"&lt;/code&gt; instead of &lt;code&gt;export&lt;/code&gt;. Don't use the watchdog in an interactive session where you would rather know about the throttle and cut parallel work.&lt;/p&gt;

&lt;h2&gt;
  
  
  Claude Code 429 vs 529: what's the difference?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;In Claude Code, a 429 means a rate limit refused the request: a short server-side throttle on a subscription, or the limit on your API key, cloud project or gateway. A 529 means the model is overloaded for everyone. Claude Code retries both, except a gateway's spend-limit 429. A 529 is never your plan's usage limit; a 429 is only when the message says &lt;code&gt;You've hit your session limit&lt;/code&gt; or &lt;code&gt;You've hit your weekly limit&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;429&lt;/th&gt;
&lt;th&gt;529&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Final message&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Server is temporarily limiting requests (not your usage limit)&lt;/code&gt; or &lt;code&gt;Request rejected (429)&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Repeated 529 Overloaded errors&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cause&lt;/td&gt;
&lt;td&gt;Rate limit on your session, key, project or gateway&lt;/td&gt;
&lt;td&gt;The model is at capacity&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Helps&lt;/td&gt;
&lt;td&gt;Fewer parallel subagents and sessions, a higher-tier key&lt;/td&gt;
&lt;td&gt;Waiting, or &lt;code&gt;/model&lt;/code&gt; to switch model&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Details&lt;/td&gt;
&lt;td&gt;This page&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  How the 429 messages changed
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.76 (March 2026)&lt;/td&gt;
&lt;td&gt;Developers reported &lt;code&gt;API Error: Rate limit reached&lt;/code&gt; (&lt;a href="https://github.com/anthropics/claude-code/issues/34413" rel="noopener noreferrer"&gt;#34413&lt;/a&gt;); that wording is not in 2.1.302 or 2.1.325&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;By April 2026&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;API Error: Server is temporarily limiting requests (not your usage limit)&lt;/code&gt; reported (&lt;a href="https://github.com/anthropics/claude-code/issues/53915" rel="noopener noreferrer"&gt;#53915&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;v2.1.186&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;CLAUDE_CODE_MAX_RETRIES&lt;/code&gt; capped at 15&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;v2.1.199&lt;/td&gt;
&lt;td&gt;Subscription sessions retry the server throttle instead of failing on the first one; with the watchdog on, other transient errors retry up to 300 times and an explicit &lt;code&gt;CLAUDE_CODE_MAX_RETRIES&lt;/code&gt; is no longer capped at 15&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;v2.1.239&lt;/td&gt;
&lt;td&gt;The watchdog stops retrying a 429 that reports a spend limit or exhausted usage credits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;v2.1.281&lt;/td&gt;
&lt;td&gt;A proxy's HTML 429 page shows only its title after the &lt;code&gt;·&lt;/code&gt;, not the whole markup&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;v2.1.295&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS&lt;/code&gt; added&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.325 (published 13 Nov 2026, checked 15 Nov)&lt;/td&gt;
&lt;td&gt;Both 429 messages and the fallback sentence present in the linux-x64 build; &lt;code&gt;API Error: Rate limit reached&lt;/code&gt; absent&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Versions from v2.1.186 on come from the &lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;error reference&lt;/a&gt; and the &lt;a href="https://code.claude.com/docs/en/env-vars" rel="noopener noreferrer"&gt;environment variable docs&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;This is the check I ran against the Claude Code 2.1.302 installed on my Windows machine (Git Bash), counting how often each message appears in the program file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;EXE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"$LOCALAPPDATA/Microsoft/WinGet/Packages/Anthropic.ClaudeCode_Microsoft.Winget.Source_8wekyb3d8bbwe/claude.exe"&lt;/span&gt;
&lt;span class="k"&gt;for&lt;/span&gt; s &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="s1"&gt;'Server is temporarily limiting requests (not your usage limit)'&lt;/span&gt; &lt;span class="s1"&gt;'Request rejected (429)'&lt;/span&gt; &lt;span class="s1"&gt;'this may be a temporary capacity issue.'&lt;/span&gt; &lt;span class="s1"&gt;'API Error: Rate limit reached'&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; &lt;span class="k"&gt;do&lt;/span&gt;
  &lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s1"&gt;'%s =&amp;gt; '&lt;/span&gt; &lt;span class="s2"&gt;"$s"&lt;/span&gt;&lt;span class="o"&gt;;&lt;/span&gt; grep -a -c -F &lt;span class="s2"&gt;"$s"&lt;/span&gt; &lt;span class="s2"&gt;"$EXE"&lt;/span&gt;
&lt;span class="k"&gt;done&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Server is temporarily limiting requests (not your usage limit) =&amp;gt; 2
Request rejected (429) =&amp;gt; 2
this may be a temporary capacity issue. =&amp;gt; 2
API Error: Rate limit reached =&amp;gt; 0
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The old &lt;code&gt;API Error: Rate limit reached&lt;/code&gt; wording is gone; the two current messages and their fallback sentence are there.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Code error 429 is a rate limit, shown as 'API Error: Server is temporarily limiting requests (not your usage limit)' on a claude.ai subscription or gateway, or 'API Error: Request rejected (429)' with an API key, Bedrock, Vertex AI or Foundry.&lt;/li&gt;
&lt;li&gt;Neither is your plan's usage limit. A real plan limit says 'You've hit your session limit' or 'You've hit your weekly limit' with a reset time.&lt;/li&gt;
&lt;li&gt;Claude Code has already retried a temporary 429 up to 10 times before you see it, so resending in a loop only adds requests.&lt;/li&gt;
&lt;li&gt;For the server throttle: wait, run fewer subagents and sessions at once, and check status.claude.com.&lt;/li&gt;
&lt;li&gt;For Request rejected (429): run /status to confirm the credential (a stray ANTHROPIC_API_KEY is a common cause), then check that key's or project's rate limits.&lt;/li&gt;
&lt;li&gt;For unattended runs, CLAUDE_CODE_RETRY_WATCHDOG=1 waits out 429s, and CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS caps the wait.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;If the model itself is overloaded rather than you being limited, see &lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded&lt;/a&gt;. If Claude Code asks you to log in instead, see &lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;Claude Code not logged in&lt;/a&gt;. Every other Claude Code error is in the &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;Claude Code troubleshooting&lt;/a&gt; hub.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What does Claude Code error 429 mean?
&lt;/h3&gt;

&lt;p&gt;HTTP 429 means Too Many Requests: something between Claude Code and the model refused the request because of a rate limit. Claude Code shows it in two forms. 'API Error: Server is temporarily limiting requests (not your usage limit)' is a short server-side throttle for claude.ai subscription and gateway sign-ins. 'API Error: Request rejected (429)' is the rate limit of your Anthropic API key, Amazon Bedrock, Google Vertex AI or Microsoft Foundry project.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is 'Server is temporarily limiting requests' my usage limit?
&lt;/h3&gt;

&lt;p&gt;No. The message says so in brackets: 'not your usage limit'. Claude Code shows it when a 429 arrives without the quota headers that a real plan-limit response carries. When you really hit your plan's limit, Claude Code says 'You've hit your session limit' or 'You've hit your weekly limit' with a reset time instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I fix 'API Error: Server is temporarily limiting requests (not your usage limit)'?
&lt;/h3&gt;

&lt;p&gt;Wait a minute and send the message again, because Claude Code (v2.1.199 or later) has already retried it up to 10 times. If it keeps coming back, run fewer subagents and Claude Code sessions at the same time, since several developers on GitHub report it while running agent teams or parallel sessions, and check status.claude.com for an incident.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I fix 'API Error: Request rejected (429)'?
&lt;/h3&gt;

&lt;p&gt;Run /status and confirm the active credential is the one you expect; a stray ANTHROPIC_API_KEY can send requests through a low-tier key instead of your subscription. Then check the key's or project's rate limits in the Claude Console, Amazon Bedrock or Google Cloud console, request a higher tier if needed, and run fewer parallel subagents.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Claude Code retry a 429 automatically?
&lt;/h3&gt;

&lt;p&gt;Yes. Claude Code retries temporary 429 throttles up to 10 times with exponential backoff before showing the error, and shows 'Retrying in Ns · attempt x/y' while it waits. CLAUDE_CODE_MAX_RETRIES changes the count. CLAUDE_CODE_RETRY_WATCHDOG=1 retries 429 and 529 errors indefinitely for unattended runs. A gateway's spend-limit 429 is not retried.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the difference between a 429 and a 529 in Claude Code?
&lt;/h3&gt;

&lt;p&gt;In Claude Code, a 429 means a rate limit refused the request: a short server-side throttle on a subscription, or the limit on your API key, cloud project or gateway. A 529 means the model is overloaded for everyone, and after repeated failures Claude Code shows 'Repeated 529 Overloaded errors'. A 529 is never your plan's usage limit; a 429 is only when the message says 'You've hit your session limit' or 'You've hit your weekly limit'.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does a 429 error use up my Claude usage?
&lt;/h3&gt;

&lt;p&gt;Anthropic does not document that a rejected request counts against your plan. Several developers in the main GitHub issue (#53915) report their usage meter rising while they kept getting 'Server is temporarily limiting requests', but Anthropic has not confirmed it. Stop resending in a loop and wait instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  What was 'API Error: Rate limit reached' in Claude Code?
&lt;/h3&gt;

&lt;p&gt;It was an older wording, reported on Claude Code 2.1.76 in March 2026 (GitHub #34413). Current builds, including 2.1.302 and 2.1.325, no longer contain it; they show 'Server is temporarily limiting requests (not your usage limit)' or 'Request rejected (429)' instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why do I get a 429 with 'Too Many Requests' after the dot?
&lt;/h3&gt;

&lt;p&gt;A proxy, load balancer or gateway between Claude Code and the API answered with its own HTML 429 page, and Claude Code shows that page's title after the '·'. The limit is on that proxy or gateway, not on Anthropic's API, so check its rate limit settings or ask whoever runs it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;Error reference: Server is temporarily limiting requests, Request rejected (429), Automatic retries (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/env-vars" rel="noopener noreferrer"&gt;Environment variables: CLAUDE_CODE_MAX_RETRIES, CLAUDE_CODE_RETRY_WATCHDOG (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://platform.claude.com/docs/en/api/rate-limits" rel="noopener noreferrer"&gt;Rate limits (Claude API docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/53915" rel="noopener noreferrer"&gt;[BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited (anthropics/claude-code issue #53915)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/34413" rel="noopener noreferrer"&gt;[BUG] API Error: Rate limit reached (anthropics/claude-code issue #34413, Claude Code 2.1.76)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@anthropic-ai/claude-code" rel="noopener noreferrer"&gt;@anthropic-ai/claude-code 2.1.325 (npm), message strings read from the linux-x64 build&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-error-429" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>devops</category>
      <category>claudecode</category>
    </item>
    <item>
      <title>I read Codex's source to see what 'Selected model is at capacity' really means</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Sun, 15 Nov 2026 12:01:56 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-read-codexs-source-to-see-what-selected-model-is-at-capacity-really-means-3432</link>
      <guid>https://dev.to/its-tahir/i-read-codexs-source-to-see-what-selected-model-is-at-capacity-really-means-3432</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-selected-model-is-at-capacity" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;If Codex keeps telling you 'Selected model is at capacity', it isn't your usage limit. I went through the Codex 0.167.2 source and its own retry tests to see what happens before that message appears (it has usually tried 5 times already), and why one conversation can keep failing while a new chat works. Have you hit it on one model, or on all of them at once?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;"Selected model is at capacity. Please try a different model." is OpenAI's Codex coding agent (the CLI, the Codex app and the IDE extension) telling you that OpenAI's servers don't have room to run that model for you right now. Codex shows it when the server answers HTTP 503 with the error code &lt;code&gt;server_is_overloaded&lt;/code&gt;; it is not your usage limit, which has its own message. In Codex 0.167.2 the request has usually been retried quietly up to 4 times (5 attempts) before you see it. The fix: wait a minute and resend, then switch model (&lt;code&gt;/model&lt;/code&gt;, the model picker, or &lt;code&gt;codex -m&lt;/code&gt;), and if only one conversation keeps failing, start a new thread with a summary of the task.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;th&gt;What to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Selected model is at capacity. Please try a different model.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;OpenAI is short of capacity for this model (503, &lt;code&gt;server_is_overloaded&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;Wait and resend, then switch model&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The same error on every model you try&lt;/td&gt;
&lt;td&gt;Capacity is short across several models at once&lt;/td&gt;
&lt;td&gt;Try a different model family or size, check &lt;a href="https://status.openai.com" rel="noopener noreferrer"&gt;status.openai.com&lt;/a&gt;, wait&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;One conversation fails, a new chat works&lt;/td&gt;
&lt;td&gt;Reported, not explained by OpenAI (details below)&lt;/td&gt;
&lt;td&gt;New thread with a short summary of the task&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Only your account, for days, while others work&lt;/td&gt;
&lt;td&gt;Reported by one user, who says OpenAI Support cited account restrictions (details below)&lt;/td&gt;
&lt;td&gt;Contact OpenAI support with the app's Feedback ID&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;Reconnecting... 1/5&lt;/code&gt; before the error&lt;/td&gt;
&lt;td&gt;Codex is retrying: the server sent a &lt;code&gt;Retry-After&lt;/code&gt; hint with the overload, or the connection dropped&lt;/td&gt;
&lt;td&gt;Let it finish; if it ends in the capacity message, switch model; behind a proxy or VPN, check it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You’ve hit your usage limit...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your plan's limit, not capacity&lt;/td&gt;
&lt;td&gt;Wait for the reset time it shows, or add credits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Policy-restricted capacity is unavailable. Please try again later.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The same shortage on a policy-restricted route&lt;/td&gt;
&lt;td&gt;Try again later&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Flex capacity unavailable.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You asked for the flex service tier and it had no room&lt;/td&gt;
&lt;td&gt;Use the default tier&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Your model vanished from the picker&lt;/td&gt;
&lt;td&gt;Your account's model catalog changed (details below)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;codex debug models&lt;/code&gt;, pick a listed model, update Codex&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 12 November 2026, against Codex 0.167.2. The error codes and retry rules come from the 0.167.2 source code on GitHub, including Codex's own tests for overloads. I also downloaded the 0.167.2 Linux package from npm and searched it for the on-screen messages, without running it. I can't make OpenAI's servers run out of capacity on demand, so the behaviour below is what the code and its tests do, plus what users report in the issues I link, not a reproduction from my own sessions. The message text is defined in Codex's own source, so this post covers Codex only.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdbb0gnhdhajzit89vzts.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fdbb0gnhdhajzit89vzts.png" alt="Where 'Selected model is at capacity' comes from in Codex 0.167.2. OpenAI answers HTTP 503 with server_is_overloaded. Codex retries the request quietly up to request_max_retries times, default 4, so up to 5 attempts. If the server sent a Retry-After header, Codex runs further rounds and shows Reconnecting... 1/5 up to stream_max_retries, default 5. If not, the turn ends with: Selected model is at capacity. Please try a different model. An overload in the middle of a streamed reply ends the turn at once with no retry. Your usage limit is a different message: You've hit your usage limit." width="800" height="578"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;By the time you read the message, Codex has usually already tried several times. Waiting or switching model is what's left.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "Selected model is at capacity" mean?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;In Codex, "Selected model is at capacity" means OpenAI's servers turned the request down because they can't serve that model for you at that moment.&lt;/strong&gt; The server answers with HTTP status 503 and an error body whose code is &lt;code&gt;server_is_overloaded&lt;/code&gt;, and Codex turns that into the message you see. The same code can also arrive inside a streamed reply that fails halfway, with the same result.&lt;/p&gt;

&lt;p&gt;An OpenAI engineer on the Codex team (GitHub user etraut-openai) answered a user who was seeing it with only 10% of their plan used:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;If you receive this message, it does not mean that you are being rate limited or are out of usage. It means that we are running low on capacity to serve this model in your region.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;That was in &lt;a href="https://github.com/openai/codex/issues/19583" rel="noopener noreferrer"&gt;openai/codex #19583&lt;/a&gt; in May 2026. Two things follow from it. Capacity is per model, which is why the message tells you to try a different one. And it depends on demand at that moment, which is why the same prompt can fail one minute and work a few minutes later.&lt;/p&gt;

&lt;p&gt;Bug reports from the Codex app often quote it as &lt;code&gt;codexErrorInfo: serverOverloaded&lt;/code&gt;. That is the same error under its internal name.&lt;/p&gt;

&lt;p&gt;Codex shows this fixed sentence whatever text the server sent with the error. In Codex's own tests, a server reply that carries the same code with the message "This model is disabled." still reaches you as "Selected model is at capacity." That's a test fixture, not something OpenAI is known to send, but it shows the message tells you the error code, not the server's reason.&lt;/p&gt;

&lt;p&gt;If you saw a similar message in ChatGPT itself rather than in Codex, it's likely the same kind of shortage on OpenAI's side, but I haven't checked ChatGPT's wording.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is "Selected model is at capacity" my usage limit?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;No. With a ChatGPT sign-in, Codex's usage-limit messages start with "You've hit your usage limit" and usually give a reset time; spend and credit limits show "Quota exceeded. Check your plan and billing details." The capacity message is neither.&lt;/strong&gt; In Codex 0.167.2 the usage-limit messages come from a separate error, &lt;code&gt;UsageLimitReached&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You’ve hit your usage limit. Try again at &amp;lt;time&amp;gt;.
You’ve hit your usage limit for &amp;lt;limit name&amp;gt;. Switch to another model now, or try again at &amp;lt;time&amp;gt;.
You’ve hit your usage limit. Upgrade to Pro (https://chatgpt.com/explore/pro), visit https://chatgpt.com/settings/usage to purchase more credits...
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The capacity message never mentions your plan or a reset time. In &lt;a href="https://github.com/openai/codex/issues/58824" rel="noopener noreferrer"&gt;#58824&lt;/a&gt;, one user seeing it on most turns had used about 82% of their weekly Codex usage with no limit reached. If you want to be sure, open your usage page in Codex or at chatgpt.com: if there's room left and you still see the capacity message, the shortage is on OpenAI's side.&lt;/p&gt;

&lt;p&gt;Codex has a few look-alike messages. This is what each one is, from the 0.167.2 source:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Message&lt;/th&gt;
&lt;th&gt;Server code&lt;/th&gt;
&lt;th&gt;Retried by Codex?&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Selected model is at capacity. Please try a different model.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;server_is_overloaded&lt;/code&gt; (503)&lt;/td&gt;
&lt;td&gt;Request retries; more rounds only with &lt;code&gt;Retry-After&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Policy-restricted capacity is unavailable. Please try again later.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;policy_capacity_unavailable&lt;/code&gt; (503)&lt;/td&gt;
&lt;td&gt;Request retries; more rounds only with &lt;code&gt;Retry-After&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Flex capacity unavailable.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;flex_unavailable&lt;/code&gt; (429)&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;We’re currently experiencing high demand, which may cause temporary errors.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;an internal server error&lt;/td&gt;
&lt;td&gt;Yes, with backoff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;exceeded retry limit, last status: 503 ...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;a retryable error, such as a plain 503, after the retries ran out&lt;/td&gt;
&lt;td&gt;Only with &lt;code&gt;Retry-After&lt;/code&gt;; otherwise this is the end of the retries&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;You’ve hit your usage limit...&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;your plan's usage limit&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Quota exceeded. Check your plan and billing details.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;insufficient_quota&lt;/code&gt; and other spend or credit limits&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  How do I fix "Selected model is at capacity"?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Work down this list in order; the first two steps cost nothing.&lt;/strong&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Wait a minute, then send the message again.&lt;/strong&gt; Capacity can change from minute to minute. The conversation isn't deleted; only the failed turn ends. Copy any long prompt you typed first, in case you need it in a new thread.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Switch to another model.&lt;/strong&gt; In the CLI, type &lt;code&gt;/model&lt;/code&gt; and choose a different model or reasoning effort. In the Codex app (Codex Desktop) or the IDE extension, use the model picker. Any other model is worth a try: in &lt;a href="https://github.com/openai/codex/issues/19583" rel="noopener noreferrer"&gt;#19583&lt;/a&gt;, commenters kept working by moving from GPT-5.5 to GPT-5.4, while in other reports several models failed at once.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If only this conversation fails, start a new thread.&lt;/strong&gt; Ask the old thread for nothing more; paste a short summary of the task into a new one (what you're doing, which files, what's done, what's next). See why one conversation can keep failing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check &lt;a href="https://status.openai.com" rel="noopener noreferrer"&gt;status.openai.com&lt;/a&gt;.&lt;/strong&gt; If there's an incident for Codex or the model, waiting is the fix.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Update Codex.&lt;/strong&gt; Each release can change the model catalog and how errors are handled. &lt;code&gt;npm install -g @openai/codex@latest&lt;/code&gt; updates the CLI; update the app or IDE extension the usual way.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If it's only your account, for days, contact OpenAI support.&lt;/strong&gt; Include the Feedback ID the Codex app gives you. See the account-level report below.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;If you set &lt;code&gt;service_tier&lt;/code&gt;, remove it.&lt;/strong&gt; A non-default tier such as flex has its own capacity and its own message (&lt;code&gt;Flex capacity unavailable.&lt;/code&gt;), and Codex doesn't retry it.&lt;/li&gt;
&lt;/ol&gt;

&lt;h3&gt;
  
  
  How do I switch models in Codex?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;In the Codex CLI, type &lt;code&gt;/model&lt;/code&gt; and pick another model and reasoning effort; in the Codex app and IDE extension, use the model picker.&lt;/strong&gt; To pick a model when you start, pass it on the command line or set it in your config:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;codex -m gpt-6.1-terra
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="c1"&gt;# ~/.codex/config.toml
&lt;/span&gt;&lt;span class="na"&gt;model&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"gpt-6.1-terra"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Use a model your account can actually use; &lt;code&gt;codex debug models&lt;/code&gt; lists them. If you're comparing options, the &lt;a href="https://tools.its-tahir.com/model-ids/openai" rel="noopener noreferrer"&gt;OpenAI model IDs list&lt;/a&gt; has the exact names, and &lt;a href="https://tools.its-tahir.com/guides/choose-model-for-coding-agents" rel="noopener noreferrer"&gt;choosing a model for coding agents&lt;/a&gt; covers the trade-offs between a heavier and a lighter model.&lt;/p&gt;

&lt;h2&gt;
  
  
  Does Codex retry "Selected model is at capacity" automatically?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Partly. Codex 0.167.2 quietly retries an HTTP 503 overload up to 4 times (&lt;code&gt;request_max_retries&lt;/code&gt;, so up to 5 attempts) before you see the message, and keeps going with &lt;code&gt;Reconnecting... 1/5&lt;/code&gt; rounds only if the server sends a &lt;code&gt;Retry-After&lt;/code&gt; header.&lt;/strong&gt; The rules, from its source and the tests that check them:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A 503 overload on a request is retried up to &lt;code&gt;request_max_retries&lt;/code&gt; times.&lt;/strong&gt; The default is 4, so Codex makes up to 5 attempts. You see nothing while that happens.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;More rounds happen only if the server sends a &lt;code&gt;Retry-After&lt;/code&gt; header.&lt;/strong&gt; Then Codex starts the whole request again, shows &lt;code&gt;Reconnecting... 1/5&lt;/code&gt;, &lt;code&gt;2/5&lt;/code&gt; and so on up to &lt;code&gt;stream_max_retries&lt;/code&gt; (default 5), waiting as long as the server asked each time. Each round repeats the quiet attempts, so with the defaults that can add up to 30 requests. Without that header, the turn ends with the capacity message after the request retries. &lt;code&gt;Reconnecting&lt;/code&gt; also appears for dropped connections and stream errors, so seeing it doesn't by itself mean an overload.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An overload that arrives in the middle of a streamed reply is never retried.&lt;/strong&gt; Codex's tests check this explicitly: one request, then the error, even if the server sent a &lt;code&gt;Retry-After&lt;/code&gt; hint.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The error ends the turn.&lt;/strong&gt; In the CLI's source, an overload error ends the turn and then sends any message you queued while Codex was working. The CLI also has a fallback text, &lt;code&gt;Codex is currently experiencing high load.&lt;/code&gt;, for an overload that arrives with no message.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Can you raise the retry counts? &lt;code&gt;request_max_retries&lt;/code&gt; and &lt;code&gt;stream_max_retries&lt;/code&gt; are settings on a model provider, and Codex's docs show them on custom providers. The same docs say you can't redefine the built-in &lt;code&gt;openai&lt;/code&gt; provider, so with a normal ChatGPT sign-in there's no documented way to make Codex retry more. More retries wouldn't create capacity anyway; waiting or switching model does more.&lt;/p&gt;

&lt;p&gt;This is a lot less patient than Claude Code, which retries its own overload error up to 10 times; &lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code's 529 Overloaded&lt;/a&gt; covers that side.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does only one Codex conversation say the model is at capacity?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;OpenAI hasn't explained why one Codex conversation can keep failing with "Selected model is at capacity" while a new chat works; the first thing to try is a new thread.&lt;/strong&gt; In &lt;a href="https://github.com/openai/codex/issues/59059" rel="noopener noreferrer"&gt;openai/codex #59059&lt;/a&gt; (opened 3 November 2026, still open), an existing conversation on Codex Desktop failed with &lt;code&gt;Selected model is at capacity&lt;/code&gt; on every model the user tried, and forking the conversation from an earlier message failed too. A brand-new, empty conversation on the same model, GPT-6.1 Sol, answered at once.&lt;/p&gt;

&lt;p&gt;The reporter kept testing the same day with Codex CLI 0.166.0. A text-only prompt failed inside a project folder and worked from its parent folder, which pointed at what Codex loads per project. Earlier, one CLI run had worked after they set their local proxy environment variables, but the next run failed again, so they called that "not a durable fix". Their later tests ruled that out: with project instructions turned off (&lt;code&gt;-c project_doc_max_bytes=0&lt;/code&gt;) the project folder still failed, and the parent folder failed on a later request too. In their own words, the parent folder "is not a reliable workaround", and no single cause was established. No OpenAI reply on the issue at the time of writing.&lt;/p&gt;

&lt;p&gt;What you can do: start a new thread and paste in a short summary of the task. It's the workaround the original report found, though later comments show new threads can fail too. If they do, treat it like the every-model case below.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does every model say it's at capacity?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Codex shows the capacity error on every model when OpenAI is short of capacity for several models at once.&lt;/strong&gt; The OpenAI engineer quoted above describes capacity for a given model in your region, so a shortage can hit one model or several. &lt;a href="https://github.com/openai/codex/issues/43375" rel="noopener noreferrer"&gt;#43375&lt;/a&gt; reports the error across GPT-5 and GPT-6 models together, and &lt;a href="https://github.com/openai/codex/issues/58824" rel="noopener noreferrer"&gt;#58824&lt;/a&gt; has one commenter reporting 90% or more of turns failing on clean threads, on every model variant, from 1 November 2026. Nothing in your local setup is known to cause it; the 503 comes from OpenAI's side.&lt;/p&gt;

&lt;p&gt;In that situation, try whichever other models you have, and if those fail too, check &lt;a href="https://status.openai.com" rel="noopener noreferrer"&gt;status.openai.com&lt;/a&gt; and give it some time. Reinstalling Codex won't create capacity.&lt;/p&gt;

&lt;p&gt;The same commenter adds something worth knowing if it's only you. They say colleagues in the same office, on the same network, used GPT-6.1 Sol normally while their own account kept getting the capacity message, and they quote OpenAI Support's reply to their case: "access to certain models or features may be temporarily restricted due to account activity." They also say OpenAI cleared mistaken policy warnings on their accounts on 3 November, and that the errors continued afterwards. That's one user's report, not something OpenAI has confirmed for this error. If the message persists for days on your account only while others work, contact OpenAI support and include the Feedback ID from the Codex app.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why did my model disappear from the Codex model picker?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Because Codex refreshes your model catalog from OpenAI, and the refreshed list can be different from the one bundled with your version.&lt;/strong&gt; In &lt;a href="https://github.com/openai/codex/issues/60676" rel="noopener noreferrer"&gt;#60676&lt;/a&gt;, GPT-6.1 Sol vanished from the VS Code extension's picker on 10 November 2026; the user found it in the catalog bundled with their Codex but not in the refreshed one, which had GPT-6.1 Terra instead. The issue was closed as completed the next day.&lt;/p&gt;

&lt;p&gt;To see what's going on with your own account:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;codex debug models            &lt;span class="c"&gt;# the catalog Codex refreshed for your account&lt;/span&gt;
codex debug models --bundled  &lt;span class="c"&gt;# the catalog that shipped with this version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the model you set in &lt;code&gt;config.toml&lt;/code&gt; isn't in the first list, pick one that is. Since 0.164.0, Codex also reloads the catalog after you switch accounts, so a model can appear or disappear when you change between a personal and a work account.&lt;/p&gt;

&lt;h2&gt;
  
  
  Codex "at capacity" vs Claude Code "Overloaded"
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Both mean the provider is out of room, and neither is your usage limit; they differ in how hard the client tries before giving up.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Codex 0.167.2&lt;/th&gt;
&lt;th&gt;Claude Code&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Message&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Selected model is at capacity. Please try a different model.&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;API Error: 529 Overloaded&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;HTTP status&lt;/td&gt;
&lt;td&gt;503, code &lt;code&gt;server_is_overloaded&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;529&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Automatic retries&lt;/td&gt;
&lt;td&gt;Up to 4 request retries; more only with &lt;code&gt;Retry-After&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Up to 10, with backoff&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Your usage limit?&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;td&gt;No&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Suggested first move&lt;/td&gt;
&lt;td&gt;Switch model&lt;/td&gt;
&lt;td&gt;Switch model with &lt;code&gt;/model&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The Claude Code side is in &lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded&lt;/a&gt;, and the &lt;a href="https://tools.its-tahir.com/errors/api-error-529-overloaded" rel="noopener noreferrer"&gt;529 Overloaded error page&lt;/a&gt; on my tools site has the short version. If Claude Code instead says there's an issue with the selected model, that's a different problem: see &lt;a href="https://www.its-tahir.com/blog/claude-code-issue-with-the-selected-model" rel="noopener noreferrer"&gt;There's an issue with the selected model&lt;/a&gt;. For Codex's other recent changes, see &lt;a href="https://www.its-tahir.com/blog/codex-auto-compact" rel="noopener noreferrer"&gt;Codex auto compact&lt;/a&gt; and &lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;Codex auto mode&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changed recently?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Nothing in 0.167.0 to 0.167.2 changes how Codex handles the capacity error; the late-October releases changed the model catalog around it.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0.164.0&lt;/td&gt;
&lt;td&gt;23 Oct 2026&lt;/td&gt;
&lt;td&gt;The model catalog reloads after you change accounts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.165.0&lt;/td&gt;
&lt;td&gt;27 Oct 2026&lt;/td&gt;
&lt;td&gt;Codex stops retrying when the provider says a model doesn't exist, and keeps the provider's message&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.166.0&lt;/td&gt;
&lt;td&gt;29 Oct 2026&lt;/td&gt;
&lt;td&gt;GPT-6.1 Terra added to the bundled model catalogs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.167.0 to 0.167.2&lt;/td&gt;
&lt;td&gt;6 to 11 Nov 2026&lt;/td&gt;
&lt;td&gt;No capacity-related changes in the release notes&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The dates are the dates on &lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex's GitHub releases&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;'Selected model is at capacity. Please try a different model.' means OpenAI answered HTTP 503 with server_is_overloaded for that model. It's a capacity shortage, not your usage limit.&lt;/li&gt;
&lt;li&gt;Usage limits have their own messages, starting 'You've hit your usage limit' and usually giving a reset time.&lt;/li&gt;
&lt;li&gt;Codex 0.167.2 has usually retried the request up to 4 times before you see the error; more rounds ('Reconnecting... 1/5') only happen when the server sends Retry-After.&lt;/li&gt;
&lt;li&gt;Fix in order: wait and resend, switch model (/model, the model picker, codex -m), start a new thread if only one conversation fails, check status.openai.com, update Codex.&lt;/li&gt;
&lt;li&gt;If a model vanished from the picker, compare codex debug models with codex debug models --bundled.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  Related
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-529-overloaded-retry-behaviour" rel="noopener noreferrer"&gt;Claude Code 529 Overloaded: what it retries for you, and what it won't&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-auto-compact" rel="noopener noreferrer"&gt;Codex auto compact: when it triggers, and how to control it&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;Codex auto mode: how to turn on Approve for me, and why it still asks&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-issue-with-the-selected-model" rel="noopener noreferrer"&gt;Claude Code "There's an issue with the selected model"&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-crashpad-pending-disk-space" rel="noopener noreferrer"&gt;Codex Crashpad 'pending' eating your Mac's disk&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What does 'Selected model is at capacity' mean in Codex?
&lt;/h3&gt;

&lt;p&gt;OpenAI's servers rejected the request because they don't have room to serve that model right now. Codex shows this message when the server answers HTTP 503 with the error code server_is_overloaded. An OpenAI engineer on the Codex repository put it this way: it means OpenAI is 'running low on capacity to serve this model in your region'. It is not your usage limit.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is 'Selected model is at capacity' my usage limit?
&lt;/h3&gt;

&lt;p&gt;No. With a ChatGPT sign-in, Codex's usage-limit messages start with 'You've hit your usage limit' and usually give a reset time; spend and credit limits show 'Quota exceeded. Check your plan and billing details.' 'Selected model is at capacity' comes from a different server error code, server_is_overloaded, and appears even when your weekly usage is far from full.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I fix 'Selected model is at capacity' in Codex?
&lt;/h3&gt;

&lt;p&gt;Wait a minute and send the message again. If it keeps failing, switch to another model with /model in the CLI, the model picker in the app or IDE extension, or codex -m on the command line. If one conversation fails while new chats work, start a new thread and paste in a short summary of the task. Check status.openai.com for an incident, and update Codex.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Codex retry 'Selected model is at capacity' automatically?
&lt;/h3&gt;

&lt;p&gt;Partly. In Codex 0.167.2 an HTTP 503 overload is retried quietly up to request_max_retries times (default 4, so up to 5 attempts) before you see anything. Only if the server also sends a Retry-After header does Codex keep going with 'Reconnecting... 1/5' rounds. An overload that arrives in the middle of a streamed reply is not retried at all.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does only one Codex conversation say the model is at capacity?
&lt;/h3&gt;

&lt;p&gt;OpenAI hasn't explained it. In openai/codex issue #59059, an existing conversation and its forks failed on every model while a new empty chat worked, but the reporter later saw new project conversations fail too and found no single cause. Starting a new thread with a summary of the task is the first thing to try.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does every model say it's at capacity?
&lt;/h3&gt;

&lt;p&gt;According to an OpenAI engineer on the Codex repository, capacity is per model and per region. Several models can be short at once: issue #43375 reports the error across GPT-5 and GPT-6 models together. Try a different model, wait a few minutes, and check status.openai.com. If it's only your account for days, contact OpenAI support.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I switch models in Codex?
&lt;/h3&gt;

&lt;p&gt;In the CLI, type /model and pick another model and reasoning effort. Start a session on a specific model with codex -m , or set model in ~/.codex/config.toml. In the Codex app and IDE extension, use the model picker. Run codex debug models to list the models your account can use.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is 'Policy-restricted capacity is unavailable' in Codex?
&lt;/h3&gt;

&lt;p&gt;It's the sibling of the capacity message for a policy-restricted route, from the server code policy_capacity_unavailable. Codex 0.167.2 gives it the same retry treatment as an ordinary overload, and its text says to try again later.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.167.2/codex-rs/protocol/src/error.rs" rel="noopener noreferrer"&gt;Error messages: ServerOverloaded, PolicyCapacityUnavailable, FlexUnavailable, retry rules (openai/codex error.rs, rust-v0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.167.2/codex-rs/codex-api/src/api_bridge.rs" rel="noopener noreferrer"&gt;HTTP 503 with server_is_overloaded mapped to ServerOverloaded (openai/codex api_bridge.rs, rust-v0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.167.2/codex-rs/codex-api/src/sse/responses_error.rs" rel="noopener noreferrer"&gt;Streamed response.failed errors and their codes (openai/codex responses_error.rs, rust-v0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.167.2/codex-rs/core/tests/suite/retry_after.rs" rel="noopener noreferrer"&gt;Overload retry tests (openai/codex retry_after.rs, rust-v0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.167.2/codex-rs/model-provider-info/src/lib.rs" rel="noopener noreferrer"&gt;Retry defaults: request_max_retries 4, stream_max_retries 5 (openai/codex model-provider-info, rust-v0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/config-file/config-reference" rel="noopener noreferrer"&gt;Configuration reference: model, service_tier, request_max_retries, stream_max_retries (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/config-file/config-advanced" rel="noopener noreferrer"&gt;Advanced configuration: built-in provider IDs can't be overridden (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/19583" rel="noopener noreferrer"&gt;OpenAI engineer: the message means low capacity for this model in your region (openai/codex #19583)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/59059" rel="noopener noreferrer"&gt;Existing conversation and its forks fail while fresh chats work (openai/codex #59059)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/58824" rel="noopener noreferrer"&gt;Persistent 'Selected model is at capacity' (serverOverloaded, HTTP 503) on GPT-6.1 Sol (openai/codex #58824)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/43375" rel="noopener noreferrer"&gt;Multiple GPT-5 / GPT-6 models return 'Selected model is at capacity' (openai/codex #43375)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/60676" rel="noopener noreferrer"&gt;GPT-6.1 Sol disappears from the refreshed model catalog (openai/codex #60676)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex releases on GitHub (0.164.0 to 0.167.2)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@openai/codex" rel="noopener noreferrer"&gt;@openai/codex 0.167.2 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-selected-model-is-at-capacity" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>openai</category>
    </item>
    <item>
      <title>I Rebuilt My MCP Server on the v2 SDK and Tested What console.log Actually Breaks</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Thu, 12 Nov 2026 05:11:19 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-rebuilt-my-mcp-server-on-the-v2-sdk-and-tested-what-consolelog-actually-breaks-bcj</link>
      <guid>https://dev.to/its-tahir/i-rebuilt-my-mcp-server-on-the-v2-sdk-and-tested-what-consolelog-actually-breaks-bcj</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/how-to-build-an-mcp-server" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;I rebuilt the weather MCP server from my August tutorial on the v2 TypeScript SDK (@modelcontextprotocol/server 2.4.0), added it to Claude Code, and tested the advice everyone repeats: that one console.log breaks a stdio server. A stray line was forgiven. Text with no newline was not. Here's the full build, the real output, and the table. What's the strangest thing that has broken your MCP server?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A custom MCP server is a small program that gives an AI client such as Claude Code or Cursor new tools to call. To build one in TypeScript: install &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt; and &lt;code&gt;zod&lt;/code&gt;, register each tool with &lt;code&gt;registerTool&lt;/code&gt; and a Zod schema inside a factory, serve the factory with &lt;code&gt;serveStdio&lt;/code&gt;, compile it, test it with the MCP Inspector, then add it to Claude Code with &lt;code&gt;claude mcp add --transport stdio weather -- node /absolute/path/build/index.js&lt;/code&gt; and check that &lt;code&gt;claude mcp list&lt;/code&gt; shows &lt;code&gt;✔ Connected&lt;/code&gt;.&lt;/strong&gt;&lt;/p&gt;

&lt;p&gt;This guide is TypeScript only; the Python SDK works differently and isn't covered here.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Step&lt;/th&gt;
&lt;th&gt;Command or code&lt;/th&gt;
&lt;th&gt;What you should see&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Install&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npm install @modelcontextprotocol/server zod&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;SDK 2.4.0, Zod 4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Build&lt;/td&gt;
&lt;td&gt;&lt;code&gt;npx tsc&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;build/index.js&lt;/code&gt;, no errors&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Test&lt;/td&gt;
&lt;td&gt;The MCP Inspector, or a short client script
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;tools/list&lt;/code&gt; returns your tools (mine returned &lt;code&gt;[ 'get_alerts' ]&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Add&lt;/td&gt;
&lt;td&gt;&lt;code&gt;claude mcp add --transport stdio weather -- node /absolute/path/build/index.js&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;Added stdio MCP server weather ... to local config&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Check&lt;/td&gt;
&lt;td&gt;&lt;code&gt;claude mcp list&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;weather: node ... - ✔ Connected&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 10 November 2026. I built the server below on Windows 11 with Node 22.22.3, &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt; 2.4.0, Zod 4.6.7 and TypeScript 7.0.2, drove it with the official 2.4.0 client, and added it to Claude Code 2.1.302 in a throwaway config folder. The outputs quoted are from those runs. I didn't run the MCP Inspector itself; that section follows its docs.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fswum59nb39w7tn29w6jb.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fswum59nb39w7tn29w6jb.png" alt="Build, test and add a custom MCP server to Claude Code, tested 10 Nov 2026 with @modelcontextprotocol/server 2.4.0 and Claude Code 2.1.302. 1 Build: registerTool with a Zod inputSchema, serveStdio(createServer), npm run build. 2 Test: the MCP Inspector (npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list, per its docs) or the official client, which negotiated protocol 2026-07-28 in my run. 3 Add: claude mcp add --transport stdio weather -- node /abs/path/build/index.js. 4 Check: claude mcp list shows weather ✔ Connected. Never write to stdout: text with no newline made the call fail with Connection closed." width="800" height="578"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Four steps from code to a connected server. Test it on its own before Claude Code ever sees it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What is a custom MCP server?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;It's a normal program that speaks the Model Context Protocol, so any MCP client can discover and call the tools it offers.&lt;/strong&gt; The protocol is JSON-RPC over stdio (the client starts your program and talks to it through stdin and stdout) or over streamable HTTP. A server can offer &lt;strong&gt;tools&lt;/strong&gt; (functions the model calls), &lt;strong&gt;resources&lt;/strong&gt; (data the client reads) and &lt;strong&gt;prompts&lt;/strong&gt; (reusable templates). Most custom servers are tools only, and that's what this post builds (if an existing server already does the job, check &lt;a href="https://tools.its-tahir.com/mcp-servers" rel="noopener noreferrer"&gt;this reviewed MCP servers list&lt;/a&gt; first): a &lt;code&gt;get_alerts&lt;/code&gt; tool that returns US weather alerts from the National Weather Service.&lt;/p&gt;

&lt;p&gt;There's nothing model-specific in your code. The client (Claude Code, Cursor, VS Code, ChatGPT) handles the model; your job is to describe each tool precisely and return useful text. I spend a lot of time on the client side of this: &lt;a href="https://www.its-tahir.com/work/contextzero" rel="noopener noreferrer"&gt;ContextZero&lt;/a&gt;, the VS Code extension I maintain, exists because every agent stores its rules and memory somewhere different. MCP fixes that for tools: one server works in every client that supports the protocol.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which MCP SDK should I use?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Use &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt;, v2 of the TypeScript SDK.&lt;/strong&gt; Its README calls it "the stable release line", implementing the 2026-07-28 MCP spec, and it replaces the single &lt;code&gt;@modelcontextprotocol/sdk&lt;/code&gt; package from v1. One trap: on 10 November 2026, npm's &lt;code&gt;latest&lt;/code&gt; tag for &lt;code&gt;@modelcontextprotocol/sdk&lt;/code&gt; still pointed at 1.32.2, so tutorials that say &lt;code&gt;npm install @modelcontextprotocol/sdk&lt;/code&gt; give you v1. If you're upgrading, the two changes you'll meet first:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;v1 (&lt;code&gt;@modelcontextprotocol/sdk&lt;/code&gt;)&lt;/th&gt;
&lt;th&gt;v2 (&lt;code&gt;@modelcontextprotocol/server&lt;/code&gt;)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;server.tool(...)&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;server.registerTool(...)&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;new StdioServerTransport()&lt;/code&gt; and &lt;code&gt;await server.connect(transport)&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;serveStdio(createServer)&lt;/code&gt; with a factory&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Zod 3&lt;/td&gt;
&lt;td&gt;Zod 4 (the docs import &lt;code&gt;zod/v4&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The SDK docs point to a codemod and an upgrade guide for the rest.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I set up a TypeScript MCP server project?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;You need &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt;, &lt;code&gt;zod&lt;/code&gt;, &lt;code&gt;"type": "module"&lt;/code&gt; in &lt;code&gt;package.json&lt;/code&gt;, and Node 20 or later.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;mkdir weather-mcp &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nb"&gt;cd&lt;/span&gt; weather-mcp
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node
mkdir src
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things in &lt;code&gt;package.json&lt;/code&gt; matter: &lt;code&gt;"type": "module"&lt;/code&gt;, because the SDK is ESM, and a &lt;code&gt;bin&lt;/code&gt; entry if you'll publish the server as a command:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"module"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"bin"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"weather"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"./build/index.js"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"scripts"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nl"&gt;"build"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"tsc"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"files"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"build"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And a &lt;code&gt;tsconfig.json&lt;/code&gt;. The &lt;code&gt;"types": ["node"]&lt;/code&gt; line is new: the SDK's README notes that TypeScript 6.0 and later no longer include &lt;code&gt;@types/*&lt;/code&gt; automatically, and its type definitions reference &lt;code&gt;Buffer&lt;/code&gt;. I compiled with TypeScript 7.0.2.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"compilerOptions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"target"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"ES2022"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"module"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Node16"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"moduleResolution"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Node16"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"outDir"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"build"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"rootDir"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"src"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"strict"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"types"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"node"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"skipLibCheck"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"include"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"src"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do I register a tool?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Call &lt;code&gt;registerTool&lt;/code&gt; with a name, a config holding a &lt;code&gt;description&lt;/code&gt; and a Zod &lt;code&gt;inputSchema&lt;/code&gt;, and an async handler that returns a &lt;code&gt;content&lt;/code&gt; array.&lt;/strong&gt; In v2 you do it inside a factory function, which &lt;code&gt;serveStdio&lt;/code&gt; calls for each connection. This is &lt;code&gt;src/index.ts&lt;/code&gt;, exactly as I compiled and ran it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;#&lt;span class="o"&gt;!/&lt;/span&gt;&lt;span class="n"&gt;usr&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;bin&lt;/span&gt;&lt;span class="o"&gt;/&lt;/span&gt;&lt;span class="n"&gt;env&lt;/span&gt; &lt;span class="n"&gt;node&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;McpServer&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@modelcontextprotocol/server"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;serveStdio&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@modelcontextprotocol/server/stdio"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"zod/v4"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="no"&gt;NWS_API_BASE&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"https://api.weather.gov"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;createServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;server&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;McpServer&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"weather"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;version&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1.0.0"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="n"&gt;server&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;registerTool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="s2"&gt;"get_alerts"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="n"&gt;description&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;
        &lt;span class="s2"&gt;"Get weather alerts in force right now for a US state. Only works for US states."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="n"&gt;inputSchema&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;z&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;length&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;describe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"Two-letter US state code, for example CA or NY"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;state&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;code&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;toUpperCase&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nb"&gt;fetch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sb"&gt;`${NWS_API_BASE}/alerts/active?area=${code}`&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;headers&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="s2"&gt;"User-Agent"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"weather-mcp/1.0"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nc"&gt;Accept&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"application/geo+json"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ok&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
          &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`Alert lookup failed: HTTP ${res.status}`&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="n"&gt;isError&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;res&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;json&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;as&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;features&lt;/span&gt;&lt;span class="o"&gt;?:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;properties&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;event&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;headline&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;features&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;features&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;features&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="sb"&gt;`No active alerts for ${code}`&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
      &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;content&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
          &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="kd"&gt;type&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"text"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;features&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;f&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="sb"&gt;`${f.properties.event}: ${f.properties.headline}`&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"\n"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
          &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;server&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="nf"&gt;serveStdio&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;createServer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;"weather MCP server running on stdio"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;From that one Zod schema, the SDK builds the JSON Schema the model sees, checks arguments before your handler runs, and types the handler's arguments. Here's what my test client got back from &lt;code&gt;tools/list&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nl"&gt;"name"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"get_alerts"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"description"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Get weather alerts in force right now for a US state. Only works for US states."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="nl"&gt;"inputSchema"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="nl"&gt;"$schema"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"https://json-schema.org/draft/2020-12/schema"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"object"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"properties"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
      &lt;span class="nl"&gt;"state"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"string"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"minLength"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"maxLength"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="nl"&gt;"description"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"Two-letter US state code, for example CA or NY"&lt;/span&gt;
      &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="nl"&gt;"required"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"state"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A call for Texas on 10 November returned &lt;code&gt;Dense Fog Advisory: Dense Fog Advisory issued November 10 at 1:06AM CST until November 10 at 10:00AM CST by NWS Lubbock TX&lt;/code&gt;, followed by the other advisories in force. Wyoming returned &lt;code&gt;No active alerts for WY&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Write descriptions for the model, not for humans
&lt;/h3&gt;

&lt;p&gt;The &lt;code&gt;description&lt;/code&gt; and every &lt;code&gt;.describe()&lt;/code&gt; are the only things the model reads when deciding whether to call your tool. &lt;code&gt;"Get weather alerts in force right now for a US state"&lt;/code&gt; gets called correctly; &lt;code&gt;"Weather utility"&lt;/code&gt; doesn't. Say &lt;strong&gt;when&lt;/strong&gt; to call it, not just what it does: "Only works for US states" stops the model calling it for Lahore and wasting a round trip.&lt;/p&gt;

&lt;p&gt;Keep the description true to the code, too. &lt;code&gt;/alerts&lt;/code&gt; and &lt;code&gt;/alerts/active&lt;/code&gt; differ by one path segment and, for Wyoming on the day I first wrote this, by 119 results against 7. The first is every alert on file; the second is the ones in force. A tool that promises "in force right now" and calls &lt;code&gt;/alerts&lt;/code&gt; makes the model report expired warnings as current, with full confidence. Nothing type-checks a description.&lt;/p&gt;

&lt;h3&gt;
  
  
  How should an MCP tool report errors?
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;Return a normal result with &lt;code&gt;isError: true&lt;/code&gt;, not an exception.&lt;/strong&gt; When the weather service fails, the handler returns a normal result with &lt;code&gt;isError: true&lt;/code&gt; instead of throwing. The model reads that text and can retry or route around it. The SDK does the same for bad arguments. When my client sent &lt;code&gt;state: "California"&lt;/code&gt;, the handler never ran, and the result was:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Input validation error: Invalid arguments for tool get_alerts: state: Too big: expected string to have exactly 2 characters
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;with &lt;code&gt;isError: true&lt;/code&gt;, so the model sees what was wrong and can fix its next call.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I serve it over stdio?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;serveStdio(createServer)&lt;/code&gt; is the whole transport.&lt;/strong&gt; It owns stdin and stdout, calls your factory for the connection, and, per the SDK docs, also serves older clients from the same factory. My test client and this server negotiated protocol version &lt;code&gt;2026-07-28&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Then compile:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;npx tsc
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a remote server that many people share, serve the same factory over streamable HTTP instead (the SDK's serving guide covers it) and add it with &lt;code&gt;claude mcp add --transport http &amp;lt;name&amp;gt; &amp;lt;url&amp;gt;&lt;/code&gt;. I only tested stdio here.&lt;/p&gt;

&lt;h3&gt;
  
  
  Never write to stdout
&lt;/h3&gt;

&lt;p&gt;&lt;strong&gt;In my test with SDK 2.4.0, a stray &lt;code&gt;console.log&lt;/code&gt; line was skipped and calls still worked, but &lt;code&gt;process.stdout.write("fetching...")&lt;/code&gt; with no newline made the next call fail with &lt;code&gt;Connection closed&lt;/code&gt;.&lt;/strong&gt; On a stdio server, stdout is the JSON-RPC channel: the client reads every line of it as a protocol message. The usual advice is that one &lt;code&gt;console.log&lt;/code&gt; breaks everything. What actually happened with the 2.4.0 client and Claude Code 2.1.302:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What the server wrote to stdout&lt;/th&gt;
&lt;th&gt;Official 2.4.0 client&lt;/th&gt;
&lt;th&gt;Claude Code 2.1.302&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;A &lt;code&gt;console.log&lt;/code&gt; line at startup&lt;/td&gt;
&lt;td&gt;Skipped; calls worked&lt;/td&gt;
&lt;td&gt;Still &lt;code&gt;✔ Connected&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A &lt;code&gt;console.log&lt;/code&gt; line inside the tool&lt;/td&gt;
&lt;td&gt;Skipped; the call worked&lt;/td&gt;
&lt;td&gt;Not tested&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A &lt;code&gt;console.log&lt;/code&gt; of a JSON object&lt;/td&gt;
&lt;td&gt;Raised an &lt;code&gt;invalid_union&lt;/code&gt; error event; the call still worked&lt;/td&gt;
&lt;td&gt;Not tested&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Text with no newline (&lt;code&gt;process.stdout.write("fetching...")&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;The call failed: &lt;code&gt;Connection closed&lt;/code&gt;&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Not tested&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;So current clients forgive a stray full line, but not output without a newline: it glues itself to the front of the next JSON message, which no longer parses, and the connection drops. Other clients may be stricter than these two. The rule stands: &lt;strong&gt;log with &lt;code&gt;console.error&lt;/code&gt;&lt;/strong&gt;, which goes to stderr, and check what your dependencies print at import time. If a server connects and then dies on its first call, look for stray output before anything else.&lt;/p&gt;

&lt;p&gt;HTTP servers don't have this problem; stdout is free there.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I test an MCP server before adding it to Claude Code?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Run it in the MCP Inspector, the reference test tool.&lt;/strong&gt; It ships as one package with three clients, needs Node 22.19.0 or newer, and runs through &lt;code&gt;npx&lt;/code&gt; with nothing to install:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# web UI, connected to your server over stdio&lt;/span&gt;
npx @modelcontextprotocol/inspector node build/index.js

&lt;span class="c"&gt;# scriptable: list the tools and exit (good for CI)&lt;/span&gt;
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

&lt;span class="c"&gt;# terminal UI&lt;/span&gt;
npx @modelcontextprotocol/inspector --tui node build/index.js
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the web client, click &lt;strong&gt;Connect&lt;/strong&gt;, open &lt;strong&gt;Tools&lt;/strong&gt;, and call yours with test arguments. One thing to know first, from its docs: the Inspector stores OAuth tokens and stdio &lt;code&gt;env:&lt;/code&gt; values in the OS keychain, and on machines without one (headless Linux, SSH sessions, containers) it writes them to &lt;code&gt;~/.mcp-inspector/secrets.json&lt;/code&gt;, unencrypted unless you supply a key.&lt;/p&gt;

&lt;p&gt;You can also test from code. The SDK's own guide drives a server through the official &lt;code&gt;Client&lt;/code&gt;; I connected mine over stdio with a few lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;Client&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@modelcontextprotocol/client"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;import&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="nc"&gt;StdioClientTransport&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="s2"&gt;"@modelcontextprotocol/client/stdio"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;Client&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"test-harness"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;version&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"1.0.0"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;versionNegotiation&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;mode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"auto"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;connect&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nc"&gt;StdioClientTransport&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;command&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nb"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;execPath&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;args&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"build/index.js"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;listTools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;tools&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// [ 'get_alerts' ]&lt;/span&gt;
&lt;span class="nb"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;log&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;callTool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"get_alerts"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;arguments&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;state&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"TX"&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;close&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That's also a cheap test to keep in CI next to your unit tests.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I add a custom MCP server to Claude Code?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Build it, then register the compiled file with &lt;code&gt;claude mcp add&lt;/code&gt;, putting the launch command after &lt;code&gt;--&lt;/code&gt;.&lt;/strong&gt;&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude mcp add --transport stdio weather -- node /absolute/path/to/weather-mcp/build/index.js
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On Windows I ran it from PowerShell with a &lt;code&gt;C:\&lt;/code&gt; path:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;claude&lt;/span&gt; &lt;span class="n"&gt;mcp&lt;/span&gt; &lt;span class="n"&gt;add&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt;&lt;span class="n"&gt;transport&lt;/span&gt; &lt;span class="n"&gt;stdio&lt;/span&gt; &lt;span class="n"&gt;weather&lt;/span&gt; &lt;span class="o"&gt;--&lt;/span&gt; &lt;span class="n"&gt;node&lt;/span&gt; &lt;span class="no"&gt;C&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;\&lt;span class="n"&gt;path&lt;/span&gt;\&lt;span class="n"&gt;to&lt;/span&gt;\&lt;span class="n"&gt;weather&lt;/span&gt;&lt;span class="o"&gt;-&lt;/span&gt;&lt;span class="n"&gt;mcp&lt;/span&gt;\&lt;span class="n"&gt;build&lt;/span&gt;\&lt;span class="n"&gt;index&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;js&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Claude Code 2.1.302 answered:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Added stdio MCP server weather with command: node C:\path\to\weather-mcp\build\index.js to local config
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and &lt;code&gt;claude mcp list&lt;/code&gt; health-checked it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Checking MCP server health…

weather: node C:\path\to\weather-mcp\build\index.js - ✔ Connected
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;claude mcp get weather&lt;/code&gt; shows the details, including &lt;code&gt;Scope: Local config (private to you in this project)&lt;/code&gt; and how to remove it (&lt;code&gt;claude mcp remove weather -s local&lt;/code&gt;).&lt;/p&gt;

&lt;p&gt;Four things worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The &lt;code&gt;--&lt;/code&gt; matters.&lt;/strong&gt; Claude Code's docs: it "separates Claude's own options, such as &lt;code&gt;--transport&lt;/code&gt;, &lt;code&gt;--env&lt;/code&gt;, and &lt;code&gt;--scope&lt;/code&gt;, from the command and arguments that run the server. Everything after &lt;code&gt;--&lt;/code&gt; is passed to the server untouched." Put &lt;code&gt;--env KEY=value&lt;/code&gt; before it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use absolute paths.&lt;/strong&gt; Relative paths resolve against the folder you start Claude Code in, not the config file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Local scope is the default, and it means this project only.&lt;/strong&gt; It's stored in &lt;code&gt;~/.claude.json&lt;/code&gt; under the current project's path. Use &lt;code&gt;--scope user&lt;/code&gt; for all your projects, or &lt;code&gt;--scope project&lt;/code&gt; to write &lt;code&gt;.mcp.json&lt;/code&gt; at the project root and share it through git (teammates then approve it once).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Slow to start?&lt;/strong&gt; &lt;code&gt;MCP_TIMEOUT=10000 claude&lt;/code&gt; gives servers 10 seconds to start, per the docs. In PowerShell: &lt;code&gt;$env:MCP_TIMEOUT=10000; claude&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If the status isn't &lt;code&gt;✔ Connected&lt;/code&gt;, see the troubleshooting table below.&lt;/p&gt;

&lt;h3&gt;
  
  
  Scope and transport, side by side
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Claude Code&lt;/th&gt;
&lt;th&gt;Cursor (per its docs, Aug 2026)&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;This project, shared with the team&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.mcp.json&lt;/code&gt; in the project root (&lt;code&gt;--scope project&lt;/code&gt;); commit it&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;.cursor/mcp.json&lt;/code&gt;; commit it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;This project only, private to you&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;~/.claude.json&lt;/code&gt; (&lt;code&gt;--scope local&lt;/code&gt;, the default)&lt;/td&gt;
&lt;td&gt;not documented as of August 2026&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;All your projects, private to you&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;~/.claude.json&lt;/code&gt; (&lt;code&gt;--scope user&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;~/.cursor/mcp.json&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Transports&lt;/td&gt;
&lt;td&gt;stdio, streamable HTTP, SSE (deprecated), WebSocket&lt;/td&gt;
&lt;td&gt;stdio, streamable HTTP, SSE&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Registration&lt;/td&gt;
&lt;td&gt;&lt;code&gt;claude mcp add&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;edit the JSON file&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Health check&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude mcp list&lt;/code&gt;, except WebSocket servers (use &lt;code&gt;claude mcp get &amp;lt;name&amp;gt;&lt;/code&gt; or &lt;code&gt;/mcp&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;MCP Logs in the Output panel&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;To get ready-to-paste JSON for Claude Code, Cursor or VS Code instead of hand-writing it, use &lt;a href="https://tools.its-tahir.com/mcp-config-generator" rel="noopener noreferrer"&gt;this MCP config generator&lt;/a&gt;. If you do hand-write JSON for Claude Code, an entry with a &lt;code&gt;url&lt;/code&gt; but no &lt;code&gt;type&lt;/code&gt; is read as a stdio server and skipped. The &lt;code&gt;type&lt;/code&gt; field accepts &lt;code&gt;streamable-http&lt;/code&gt; as an alias for &lt;code&gt;http&lt;/code&gt;, so configs copied from a server's docs work as they are.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why isn't my custom MCP server connecting?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Run the exact command after &lt;code&gt;--&lt;/code&gt; yourself first.&lt;/strong&gt; If it doesn't start in your shell, it won't start in Claude Code.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You see&lt;/th&gt;
&lt;th&gt;Likely cause&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;✘ Failed to connect&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The command fails: wrong path, not built, missing dependency&lt;/td&gt;
&lt;td&gt;Run it yourself; use an absolute path to &lt;code&gt;build/index.js&lt;/code&gt;; run &lt;code&gt;npx tsc&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Connects, then a call fails with &lt;code&gt;Connection closed&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Output on stdout without a newline, or the process crashed&lt;/td&gt;
&lt;td&gt;Log with &lt;code&gt;console.error&lt;/code&gt;; check stderr for a crash&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;⏸ Pending approval&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A project-scope server in &lt;code&gt;.mcp.json&lt;/code&gt; that you haven't approved&lt;/td&gt;
&lt;td&gt;Run &lt;code&gt;claude&lt;/code&gt; in the project and accept it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Not in the list at all&lt;/td&gt;
&lt;td&gt;Added at another scope, or in another project&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude mcp get &amp;lt;name&amp;gt;&lt;/code&gt;; re-add with &lt;code&gt;--scope user&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Times out at startup&lt;/td&gt;
&lt;td&gt;Slow first run, for example &lt;code&gt;npx&lt;/code&gt; downloading a package&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;MCP_TIMEOUT=10000 claude&lt;/code&gt; (PowerShell: &lt;code&gt;$env:MCP_TIMEOUT=10000; claude&lt;/code&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Each status and its fix in detail, including the Windows &lt;code&gt;npx&lt;/code&gt; case, is in &lt;a href="https://www.its-tahir.com/blog/mcp-server-not-showing-up-in-claude-code" rel="noopener noreferrer"&gt;MCP server not showing up in Claude Code&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How many tools should an MCP server have?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;As few as cover your users' intents.&lt;/strong&gt; Every tool's name, description and schema load into the model's context on every request. Twenty tools is a standing tax on every turn, and more near-synonyms make tool choice harder. Claude Code's output limits push the same way, per its docs: it warns when a tool's output exceeds 10,000 tokens, caps it at 25,000 by default (&lt;code&gt;MAX_MCP_OUTPUT_TOKENS&lt;/code&gt; changes that), and saves text results longer than 50,000 characters to a file unless the tool declares its own &lt;code&gt;anthropic/maxResultSizeChars&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Three rules I apply:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;One tool per user intent, not per API endpoint.&lt;/strong&gt; &lt;code&gt;find_overdue_invoices&lt;/code&gt; beats &lt;code&gt;list_invoices&lt;/code&gt; plus &lt;code&gt;filter_invoices&lt;/code&gt; plus &lt;code&gt;get_invoice&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Return the answer, not the payload.&lt;/strong&gt; Terse text, not your API's envelope, pagination cursors and empty fields.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Delete tools nobody calls.&lt;/strong&gt; They cost context for nothing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It's the same discipline as in &lt;a href="https://www.its-tahir.com/blog/claude-code-vs-cursor-context-management" rel="noopener noreferrer"&gt;Claude Code vs Cursor: how each one decides what your agent knows&lt;/a&gt;: context is a budget, and tool schemas spend from it whether you use them or not. If your tool fronts a search index, what it retrieves spends from the same budget, and &lt;a href="https://www.its-tahir.com/blog/rag-retrieval-returns-the-wrong-chunks" rel="noopener noreferrer"&gt;RAG retrieval that returns the wrong chunks&lt;/a&gt; covers when those results are off.&lt;/p&gt;

&lt;h2&gt;
  
  
  A checklist before you ship
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;npx tsc&lt;/code&gt; runs clean and produces &lt;code&gt;build/index.js&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Nothing writes to stdout: no &lt;code&gt;console.log&lt;/code&gt;, no &lt;code&gt;process.stdout.write&lt;/code&gt;, and no chatty dependency.&lt;/li&gt;
&lt;li&gt;Every tool's description says when to call it, and every schema field has &lt;code&gt;.describe()&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Failures return &lt;code&gt;isError: true&lt;/code&gt; results, not thrown errors.&lt;/li&gt;
&lt;li&gt;Secrets come from environment variables passed with &lt;code&gt;--env&lt;/code&gt;, never hardcoded.&lt;/li&gt;
&lt;li&gt;It passes &lt;code&gt;tools/list&lt;/code&gt; in the Inspector or your own client test.&lt;/li&gt;
&lt;li&gt;You've reviewed what it can reach. A server that fetches outside content is a prompt-injection surface; Claude Code's docs carry an explicit warning about this, and it applies to servers you write as much as ones you install.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What changed for MCP server authors recently?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;When&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;27 Jul 2026&lt;/td&gt;
&lt;td&gt;TypeScript SDK 2.0.0: &lt;code&gt;@modelcontextprotocol/server&lt;/code&gt; and &lt;code&gt;@modelcontextprotocol/client&lt;/code&gt; replace the single v1 package; &lt;code&gt;registerTool&lt;/code&gt; and &lt;code&gt;serveStdio&lt;/code&gt; replace &lt;code&gt;tool()&lt;/code&gt; and &lt;code&gt;StdioServerTransport&lt;/code&gt; with &lt;code&gt;connect()&lt;/code&gt;; Zod 4&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;28 Jul 2026&lt;/td&gt;
&lt;td&gt;MCP specification 2026-07-28&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;23 Oct 2026&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;@modelcontextprotocol/server&lt;/code&gt; 2.4.0, the version tested here&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Claude Code 2.1.91&lt;/td&gt;
&lt;td&gt;Tools can raise their own result limit with &lt;code&gt;_meta["anthropic/maxResultSizeChars"]&lt;/code&gt; (up to 500K characters); today's docs save other text results over 50,000 characters to a file&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;I tested with Claude Code 2.1.302, the version installed here; the current release is 2.1.322. Since 2.1.302 the changelog lists fixes to these commands, so your output may differ slightly: in 2.1.311, &lt;code&gt;claude mcp add&lt;/code&gt; and &lt;code&gt;remove&lt;/code&gt; name the right project entry when run below a repository root, and failed-connection lines in &lt;code&gt;claude mcp list&lt;/code&gt; and &lt;code&gt;get&lt;/code&gt; no longer repeat the error code; in 2.1.318, &lt;code&gt;add&lt;/code&gt; and &lt;code&gt;remove&lt;/code&gt; wait for the config lock; in 2.1.321, &lt;code&gt;claude mcp list&lt;/code&gt; no longer prints nothing when a stored MCP sign-in record is null.&lt;/p&gt;

&lt;p&gt;If Claude Code itself is what's failing once the server is registered, &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;every Claude Code error and its fix&lt;/a&gt; maps each message to the post that solves it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A custom MCP server is an ordinary program that speaks JSON-RPC over stdio or HTTP; the client handles the model.&lt;/li&gt;
&lt;li&gt;Use @modelcontextprotocol/server (SDK v2, protocol 2026-07-28). npm install @modelcontextprotocol/sdk still gives you v1.&lt;/li&gt;
&lt;li&gt;Register tools with registerTool and a Zod schema inside a factory, and serve it with serveStdio(createServer).&lt;/li&gt;
&lt;li&gt;Test before Claude Code sees it: the MCP Inspector (Node 22.19+) or a few lines with the official client.&lt;/li&gt;
&lt;li&gt;Add it with claude mcp add --transport stdio  -- node /absolute/path/build/index.js, then check claude mcp list for ✔ Connected.&lt;/li&gt;
&lt;li&gt;Never write to stdout. In my test a stray full line was forgiven, but text with no newline broke the next message and the call failed with Connection closed.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  How do I build a custom MCP server?
&lt;/h3&gt;

&lt;p&gt;In TypeScript: install @modelcontextprotocol/server and zod, create an McpServer inside a factory function, register each tool with registerTool and a Zod inputSchema, and serve the factory with serveStdio from @modelcontextprotocol/server/stdio. Compile it, test it with the MCP Inspector, then add it to your client. That is the whole shape; the rest is writing good tool descriptions and keeping stdout clean.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I add a custom MCP server to Claude Code?
&lt;/h3&gt;

&lt;p&gt;Build it first, then run claude mcp add --transport stdio  -- node /absolute/path/to/build/index.js. Everything after -- is passed to your server untouched. The server is added to local scope by default, which means this project only; add --scope user for all your projects or --scope project to share it through .mcp.json. Check it with claude mcp list, which should show ✔ Connected.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I use @modelcontextprotocol/sdk or @modelcontextprotocol/server?
&lt;/h3&gt;

&lt;p&gt;For a new server, @modelcontextprotocol/server. It is v2 of the TypeScript SDK, the stable line, and implements the 2026-07-28 protocol. @modelcontextprotocol/sdk is the v1 package; npm's latest tag for it still pointed at 1.32.2 on 10 November 2026, so npm install @modelcontextprotocol/sdk still gives you v1. Coming from v1, registerTool replaces tool() and serveStdio replaces new StdioServerTransport() plus server.connect().&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I test an MCP server?
&lt;/h3&gt;

&lt;p&gt;Use the MCP Inspector, which needs Node 22.19.0 or newer. npx @modelcontextprotocol/inspector node build/index.js opens the web client; add --cli and --method tools/list for a scriptable check in CI. You can also drive the server from a few lines of code with the official client, which is what I did for this post.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does my MCP server say Connection closed?
&lt;/h3&gt;

&lt;p&gt;On a stdio server, a common cause is output on stdout that corrupts the JSON-RPC stream. In my test with SDK 2.4.0, a full stray line from console.log was skipped by the client, but text written without a newline glued onto the next message and the call failed with Connection closed. Log with console.error, and check what your dependencies print. If the server never starts at all, run its command yourself to see the real error.&lt;/p&gt;

&lt;h3&gt;
  
  
  Do I need a different MCP server for Claude Code and Cursor?
&lt;/h3&gt;

&lt;p&gt;No. MCP is a protocol, not a vendor integration. The same stdio server registers with Claude Code through claude mcp add and with Cursor through an entry in .cursor/mcp.json. Only the registration differs.&lt;/p&gt;

&lt;h3&gt;
  
  
  Should I use stdio or HTTP transport?
&lt;/h3&gt;

&lt;p&gt;Use stdio when the server runs locally and needs machine access, such as files, local databases or CLIs. Use streamable HTTP when the server is remote and shared across a team, because HTTP supports OAuth. Claude Code's docs deprecate SSE in favor of HTTP.&lt;/p&gt;

&lt;h3&gt;
  
  
  How many tools should one MCP server expose?
&lt;/h3&gt;

&lt;p&gt;Fewer than you think. Every tool's name, description and schema load into the model's context on every request, and Claude Code warns when a tool's output exceeds 10,000 tokens. A few sharply described tools beat many vague ones.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@modelcontextprotocol/server" rel="noopener noreferrer"&gt;@modelcontextprotocol/server 2.4.0 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ts.sdk.modelcontextprotocol.io/v2/servers/tools" rel="noopener noreferrer"&gt;TypeScript SDK v2: Tools&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ts.sdk.modelcontextprotocol.io/v2/serving/stdio" rel="noopener noreferrer"&gt;TypeScript SDK v2: Serve over stdio&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://ts.sdk.modelcontextprotocol.io/v2/testing" rel="noopener noreferrer"&gt;TypeScript SDK v2: Test a server&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://modelcontextprotocol.io/docs/2026-07-28/tools/inspector" rel="noopener noreferrer"&gt;MCP Inspector (Model Context Protocol docs, 2026-07-28)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://modelcontextprotocol.io/docs/2026-07-28/develop/build-server" rel="noopener noreferrer"&gt;Build an MCP server (Model Context Protocol docs, 2026-07-28)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/mcp" rel="noopener noreferrer"&gt;Connect Claude Code to tools via MCP (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://cursor.com/docs/mcp" rel="noopener noreferrer"&gt;Model Context Protocol (Cursor docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.weather.gov/documentation/services-web-api" rel="noopener noreferrer"&gt;National Weather Service API&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/how-to-build-an-mcp-server" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>typescript</category>
      <category>mcp</category>
      <category>programming</category>
    </item>
    <item>
      <title>I Read Codex's Source to Find When It Auto-Compacts. It's 90%, and You Can't Turn It Off</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Tue, 10 Nov 2026 03:55:56 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-read-codexs-source-to-find-when-it-auto-compacts-its-90-and-you-cant-turn-it-off-3fd6</link>
      <guid>https://dev.to/its-tahir/i-read-codexs-source-to-find-when-it-auto-compacts-its-90-and-you-cant-turn-it-off-3fd6</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-auto-compact" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Codex users keep asking when auto compaction fires and why raising the limit doesn't delay it. So I read the 0.166.0 source: auto compaction starts at 90% of the context window (244,800 tokens on a 272K model), model_auto_compact_token_limit can only move it earlier, and there's no off switch. Here's what you can actually change. How do you keep long Codex sessions from losing the plot?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Codex auto compacts a conversation when it reaches 90% of the model's context window. In the model catalog bundled with Codex 0.166.0, most models have a 272,000-token window, so compaction starts at 244,800 tokens (your live catalog can differ; check yours): Codex shows &lt;code&gt;Compacting context&lt;/code&gt;, replaces older turns with a summary, and then shows &lt;code&gt;Context compacted&lt;/code&gt;. There is no setting that turns it off. &lt;code&gt;model_auto_compact_token_limit&lt;/code&gt; can only make it start earlier; to make it start later, raise &lt;code&gt;model_context_window&lt;/code&gt;. To keep it from interrupting work, run &lt;code&gt;/compact&lt;/code&gt; yourself or set &lt;code&gt;model_post_turn_compact_threshold_percent&lt;/code&gt; so it compacts between turns.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You want&lt;/th&gt;
&lt;th&gt;Set this in &lt;code&gt;~/.codex/config.toml&lt;/code&gt;
&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Compact earlier, at a fixed token count&lt;/td&gt;
&lt;td&gt;&lt;code&gt;model_auto_compact_token_limit = 150000&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compact later&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;model_context_window = 500000&lt;/code&gt; (up to the model's maximum)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compact between turns, not mid-task&lt;/td&gt;
&lt;td&gt;&lt;code&gt;model_post_turn_compact_threshold_percent = 70&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A different summary&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;compact_prompt = "..."&lt;/code&gt; or &lt;code&gt;experimental_compact_prompt_file = "path"&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Compact right now&lt;/td&gt;
&lt;td&gt;Type &lt;code&gt;/compact&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Turn auto compaction off&lt;/td&gt;
&lt;td&gt;Not possible in Codex 0.166.0&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 6 November 2026, against Codex 0.166.0. The threshold rules come from the 0.166.0 source code on GitHub and the bundled model catalog; settings from OpenAI's configuration reference; on-screen messages from the 0.166.0 Linux package, which I downloaded from npm and searched without running it. I couldn't run a signed-in Codex session for this post, so the numbers are what the code computes, not measurements from my own sessions.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ft6gein702q86uhq8ng7i.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ft6gein702q86uhq8ng7i.png" alt="When Codex auto compacts, Codex 0.166.0. Default 272,000-token window, the most common size in the bundled catalog: auto compact at 244,800 tokens (90%), hard cap that always compacts at 258,400 (95%). model_context_window = 872000: auto compact at 784,800. model_post_turn_compact_threshold_percent = 70: turn-end compact at 180,880, 70% of the 258,400 usable window. There is no setting that turns auto compaction off." width="800" height="556"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Auto compaction starts at 90% of the context window. The only ways to move it later are a bigger window or a manual /compact before you reach it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What is auto compact in Codex?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Auto compact is Codex summarizing its own conversation when the context window is nearly full, so a long task can keep going.&lt;/strong&gt; Every request Codex sends to the model includes the conversation so far. When that history gets close to what the model can accept, Codex replaces earlier turns with a shorter summary and carries on. In the CLI you see two lines:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Compacting context
Context compacted
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The same thing happens when you type &lt;code&gt;/compact&lt;/code&gt;; auto compaction just picks the moment for you. Codex can compact at three points in a turn: before it sends your next message, in the middle of a turn when a tool result pushes the context over the limit, and (if you turn it on) after a finished reply.&lt;/p&gt;

&lt;h2&gt;
  
  
  When does Codex auto compact?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Codex auto compacts when the active context reaches 90% of the model's context window: 244,800 tokens on a 272,000-token model in Codex 0.166.0, and 450,000 on a 500,000-token one.&lt;/strong&gt; As a rule: the threshold is the smaller of &lt;code&gt;model_auto_compact_token_limit&lt;/code&gt; and 90% of the context window, and reaching 95% of the window always forces compaction. This is the function in Codex 0.166.0 that sets it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight rust"&gt;&lt;code&gt;&lt;span class="k"&gt;pub&lt;/span&gt; &lt;span class="k"&gt;fn&lt;/span&gt; &lt;span class="nf"&gt;auto_compact_token_limit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;&amp;amp;&lt;/span&gt;&lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;-&amp;gt;&lt;/span&gt; &lt;span class="kt"&gt;Option&lt;/span&gt;&lt;span class="o"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;i64&lt;/span&gt;&lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;context_limit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;self&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;resolved_context_window&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;context_window&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context_window&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="mi"&gt;9&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="n"&gt;config_limit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nb"&gt;self&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;auto_compact_token_limit&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="kc"&gt;Some&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context_limit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;context_limit&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;Some&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
            &lt;span class="n"&gt;config_limit&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;map_or&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;context_limit&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="n"&gt;limit&lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt; &lt;span class="n"&gt;std&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="n"&gt;cmp&lt;/span&gt;&lt;span class="o"&gt;::&lt;/span&gt;&lt;span class="nf"&gt;min&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;limit&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;context_limit&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="n"&gt;config_limit&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;So it returns the smaller of that 90% figure and any limit set for the model or in your config. The model catalog bundled with 0.166.0 sets no per-model limit, so for every listed model the 90% figure is the threshold:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Model (bundled catalog, 0.166.0)&lt;/th&gt;
&lt;th&gt;Context window&lt;/th&gt;
&lt;th&gt;Auto compact at&lt;/th&gt;
&lt;th&gt;Maximum window&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;gpt-6.1-sol*, gpt-6-sol, gpt-6-luna, gpt-6-astra&lt;/td&gt;
&lt;td&gt;272,000&lt;/td&gt;
&lt;td&gt;244,800&lt;/td&gt;
&lt;td&gt;872,000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna&lt;/td&gt;
&lt;td&gt;272,000&lt;/td&gt;
&lt;td&gt;244,800&lt;/td&gt;
&lt;td&gt;872,000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;gpt-6.1-terra&lt;/td&gt;
&lt;td&gt;500,000&lt;/td&gt;
&lt;td&gt;450,000&lt;/td&gt;
&lt;td&gt;872,000&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;gpt-5.5&lt;/td&gt;
&lt;td&gt;272,000&lt;/td&gt;
&lt;td&gt;244,800&lt;/td&gt;
&lt;td&gt;272,000&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;* Two caveats. Codex downloads a fresh catalog from OpenAI and caches it, so the live values for your account can differ from the bundled file. In one user's cache from 18 October 2026, quoted in &lt;a href="https://github.com/openai/codex/issues/55008" rel="noopener noreferrer"&gt;#55008&lt;/a&gt;, gpt-6.1-sol had a 500,000-token window, which puts its threshold at 450,000. And there's a second, harder limit: 95% of the window (258,400 tokens on a 272K model) is what Codex treats as usable, and reaching it forces compaction regardless of your settings.&lt;/p&gt;

&lt;p&gt;Some summaries put the threshold at 40 to 50% of the window, or about 220,000 tokens. In Codex 0.166.0 it is 90% of the window, which is 244,800 tokens on a 272K model.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I check my own Codex compaction threshold?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Open &lt;code&gt;~/.codex/models_cache.json&lt;/code&gt; (or &lt;code&gt;models_cache.json&lt;/code&gt; in your &lt;code&gt;CODEX_HOME&lt;/code&gt;), find your model's entry, and take 90% of its &lt;code&gt;context_window&lt;/code&gt;.&lt;/strong&gt; That file is the catalog Codex downloaded for your account, so it beats any table, including mine. Three fields matter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;context_window&lt;/code&gt;: the window Codex uses. Your threshold is 90% of it.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;auto_compact_token_limit&lt;/code&gt;: if it's set, the threshold is the smaller of this and the 90% figure. In the bundled catalog it's &lt;code&gt;null&lt;/code&gt; for every model.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;max_context_window&lt;/code&gt;: the most you can raise &lt;code&gt;model_context_window&lt;/code&gt; to.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you set &lt;code&gt;model_context_window&lt;/code&gt; or &lt;code&gt;model_auto_compact_token_limit&lt;/code&gt; in &lt;code&gt;config.toml&lt;/code&gt;, those override the file, with the same 90% cap.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I change the auto compact threshold?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;&lt;code&gt;model_auto_compact_token_limit&lt;/code&gt; moves it earlier; &lt;code&gt;model_context_window&lt;/code&gt; moves it later.&lt;/strong&gt; Both go in &lt;code&gt;~/.codex/config.toml&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;To compact earlier, for example to keep each request smaller and cheaper:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="na"&gt;model_auto_compact_token_limit&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;150000&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Codex uses the smaller of your number and 90% of the window, so a value above 244,800 on a 272K model changes nothing. Raising this setting is not a way to stop compaction.&lt;/p&gt;

&lt;p&gt;To compact later, give the model a bigger window, up to the maximum listed for it in the catalog:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="na"&gt;model_context_window&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;500000&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Codex caps this at the model's &lt;code&gt;max_context_window&lt;/code&gt; (872,000 for most current models in the bundled catalog, 272,000 for gpt-5.5), and the 90% rule applies to the new size: 450,000 tokens for a 500K window, 784,800 for 872K. Keep in mind that a bigger window lets each request near the end of a long session carry more tokens, which uses more of your plan or costs more on an API key. A &lt;a href="https://tools.its-tahir.com/context-window-checker" rel="noopener noreferrer"&gt;context window checker&lt;/a&gt; helps you see whether a big file or log fits before you paste it in.&lt;/p&gt;

&lt;p&gt;There's also &lt;code&gt;model_auto_compact_token_limit_scope&lt;/code&gt;. The default, &lt;code&gt;total&lt;/code&gt;, counts the whole active context against the limit. &lt;code&gt;body_after_prefix&lt;/code&gt; counts only what's been added since the last compaction's carried-over prefix, which is for setups that want each compaction window to have a fixed budget.&lt;/p&gt;

&lt;h2&gt;
  
  
  Can I disable auto compact in Codex?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;No, not in Codex 0.166.0.&lt;/strong&gt; There's no config key, flag or slash command that turns it off for your sessions. The source does have an off switch, a thread setting called &lt;code&gt;AutoCompactionDisabled&lt;/code&gt; in &lt;code&gt;codex-rs/core/src/compact.rs&lt;/code&gt;, but only the app server sets it, for threads it starts internally. Nothing in your config can. An issue asking for more control over auto-compaction (&lt;a href="https://github.com/openai/codex/issues/4106" rel="noopener noreferrer"&gt;#4106&lt;/a&gt;) has been open since September 2025.&lt;/p&gt;

&lt;p&gt;What you can do instead:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Push it later&lt;/strong&gt; with a bigger &lt;code&gt;model_context_window&lt;/code&gt;, as above.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Choose the moment&lt;/strong&gt; by running &lt;code&gt;/compact&lt;/code&gt; at a natural break, before Codex reaches the threshold mid-task.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Move it between turns&lt;/strong&gt; with &lt;code&gt;model_post_turn_compact_threshold_percent&lt;/code&gt; (next section).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Start a new thread&lt;/strong&gt; when a task is done, instead of stretching one conversation across several tasks.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The error for a request that doesn't fit in the window reads:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Codex ran out of room in the model's context window. Start a new thread or clear earlier history before retrying.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do I compact manually?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Type &lt;code&gt;/compact&lt;/code&gt; and confirm.&lt;/strong&gt; Per OpenAI's docs, "Codex replaces earlier turns with a concise summary, freeing context while keeping critical details." Doing it yourself after a task is finished, or before you start a new one in the same thread, means the summary covers finished work instead of half-done work.&lt;/p&gt;

&lt;p&gt;Don't confuse it with &lt;code&gt;/recap&lt;/code&gt;, which summarizes the conversation for you to read and leaves the context as it is.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I stop compaction from losing my task?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Compact between turns, and keep the task somewhere a summary can't drop it.&lt;/strong&gt; A recurring complaint in Codex's issue tracker is that a summary written mid-task loses the current instruction, after which the agent asks what you'd like to work on or repeats finished steps (&lt;a href="https://github.com/openai/codex/issues/57608" rel="noopener noreferrer"&gt;#57608&lt;/a&gt;, &lt;a href="https://github.com/openai/codex/issues/57806" rel="noopener noreferrer"&gt;#57806&lt;/a&gt;, &lt;a href="https://github.com/openai/codex/issues/57983" rel="noopener noreferrer"&gt;#57983&lt;/a&gt;). Three settings help:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;model_post_turn_compact_threshold_percent&lt;/code&gt;.&lt;/strong&gt; It's off by default. Set it to compact "after a final response when active context reaches this percentage of the usable context window." At 70 on a 272K model, that is 70% of the 258,400-token usable window, so Codex compacts at 180,880 tokens once a reply is finished, usually well before the mid-task threshold. The normal limits still apply if a single turn grows past them.
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;  &lt;span class="na"&gt;model_post_turn_compact_threshold_percent&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;70&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;compact_prompt&lt;/code&gt;&lt;/strong&gt; (or &lt;code&gt;experimental_compact_prompt_file&lt;/code&gt; for a longer one) replaces the instructions Codex uses to write the summary. Tell it to keep the current task, open decisions and file paths word for word.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;PreCompact&lt;/code&gt; and &lt;code&gt;PostCompact&lt;/code&gt; hooks&lt;/strong&gt; run your own command around each compaction, for example to save the current plan to a file before the summary replaces it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The habit that works in any version: keep the task and its acceptance criteria in a file in the repo (a &lt;code&gt;TASK.md&lt;/code&gt;, or a section in &lt;code&gt;AGENTS.md&lt;/code&gt;), and tell Codex to re-read it after compaction. A file isn't part of the conversation, so no summary can lose it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does Codex compact too early?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Usually the threshold is lower than the number you're comparing it with.&lt;/strong&gt; Common reasons:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The window is smaller than the model's maximum.&lt;/strong&gt; Most current models run with a 272K window even though the catalog allows up to 872K, so compaction at about 245K is expected (check yours).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An old build.&lt;/strong&gt; Codex 0.166.0 (29 October 2026) "preserved reasoning-token accounting across resume and fork to avoid premature compaction." If compaction started early after &lt;code&gt;codex resume&lt;/code&gt; or a fork, update first. &lt;a href="https://github.com/openai/codex/issues/59081" rel="noopener noreferrer"&gt;#59081&lt;/a&gt; reports the same symptom on the Windows desktop app, on a build without that fix.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The display and the trigger measure different things.&lt;/strong&gt; Reports such as &lt;a href="https://github.com/openai/codex/issues/55126" rel="noopener noreferrer"&gt;#55126&lt;/a&gt; describe compaction while the IDE still showed about half the context free. The trigger counts active context against 90% of the window, so a remaining-context figure based on a different total can look misleading.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Images.&lt;/strong&gt; Since 0.150.1, remote compaction counts retained images toward its token budget and trims older ones.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why is Codex stuck compacting, or compacting in a loop?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Compaction itself failed or didn't free enough room.&lt;/strong&gt; When remote compaction fails, the 0.166.0 build logs &lt;code&gt;Error running remote compact task&lt;/code&gt;, and a failed turn-end compaction logs &lt;code&gt;Post-turn compaction failed; preserving the completed turn&lt;/code&gt;. Open reports describe compaction that leaves the next request no smaller, so it runs again and again (&lt;a href="https://github.com/openai/codex/issues/59534" rel="noopener noreferrer"&gt;#59534&lt;/a&gt;), and remote compaction errors that stop further replies in the desktop app (&lt;a href="https://github.com/openai/codex/issues/59475" rel="noopener noreferrer"&gt;#59475&lt;/a&gt;).&lt;/p&gt;

&lt;p&gt;What to do:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Update.&lt;/strong&gt; Codex 0.164.0 stopped failed compactions from leaving partial summaries in the history. That doesn't fix every loop (#59534 was still open on 5 November 2026), but it rules out one cause.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Find what's refilling the context.&lt;/strong&gt; If it compacts, refills straight away and compacts again, a large tool output or file read is the usual cause. Ask for smaller reads, or narrower command output.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Start a new thread&lt;/strong&gt; with a short written summary of where the task stands. A fresh thread costs less than a loop that burns usage on repeated summaries.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Is Codex compaction local or remote?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;It depends on the model provider.&lt;/strong&gt; The configuration reference describes a provider capability, &lt;code&gt;remote_compaction&lt;/code&gt;: &lt;code&gt;v2&lt;/code&gt; "sends compaction triggers through Responses", and &lt;code&gt;unsupported&lt;/code&gt; "uses local compaction." Codex reports both kinds in its &lt;code&gt;task.compact&lt;/code&gt; metric, split by type &lt;code&gt;remote&lt;/code&gt; or &lt;code&gt;local&lt;/code&gt;. Since 0.162.0 you can set the capability for custom Responses-compatible providers, and since 0.147.0 Amazon Bedrock supports remote compaction.&lt;/p&gt;

&lt;h2&gt;
  
  
  How is Codex auto compact different from Claude Code's?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Codex (0.166.0)&lt;/th&gt;
&lt;th&gt;Claude Code&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Default trigger&lt;/td&gt;
&lt;td&gt;90% of the context window (244,800 on a 272K model)&lt;/td&gt;
&lt;td&gt;The model's context limit, about 967K tokens on 1M-context models (&lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;details&lt;/a&gt;)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Change the trigger&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;model_auto_compact_token_limit&lt;/code&gt; (earlier only), &lt;code&gt;model_context_window&lt;/code&gt; (later)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/autocompact&lt;/code&gt;, or &lt;code&gt;autoCompactWindow&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Turn it off&lt;/td&gt;
&lt;td&gt;Not possible&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Auto-compact&lt;/strong&gt; in &lt;code&gt;/config&lt;/code&gt;, or &lt;code&gt;DISABLE_AUTO_COMPACT&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Manual&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/compact&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/compact&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;If you use both, the Claude Code side is in &lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;Claude Code keeps compacting&lt;/a&gt;, and its compaction during breaks is covered in &lt;a href="https://www.its-tahir.com/blog/claude-code-compacted-while-idle" rel="noopener noreferrer"&gt;Compacted while idle&lt;/a&gt;. For how each tool decides what it may run without asking, see &lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;Codex auto mode&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changed in Codex compaction recently?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Between 0.147.0 and 0.166.0 (August to October 2026), Codex brought remote compaction to Bedrock and custom providers, made failed compactions clean up after themselves, and fixed early compaction after resume.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0.147.0&lt;/td&gt;
&lt;td&gt;7 Aug 2026&lt;/td&gt;
&lt;td&gt;Remote compaction for Amazon Bedrock&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.150.0&lt;/td&gt;
&lt;td&gt;26 Aug 2026&lt;/td&gt;
&lt;td&gt;Compaction fixed for Amazon Bedrock models&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.150.1&lt;/td&gt;
&lt;td&gt;27 Aug 2026&lt;/td&gt;
&lt;td&gt;Remote compaction counts retained images toward its token budget&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.155.0&lt;/td&gt;
&lt;td&gt;17 Sep 2026&lt;/td&gt;
&lt;td&gt;Accepted prompts are saved even when compaction fails before a turn starts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.162.0&lt;/td&gt;
&lt;td&gt;8 Oct 2026&lt;/td&gt;
&lt;td&gt;Remote compaction capability configurable for custom Responses-compatible providers&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.164.0&lt;/td&gt;
&lt;td&gt;23 Oct 2026&lt;/td&gt;
&lt;td&gt;Failed compaction no longer leaves partial summaries in history&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.166.0&lt;/td&gt;
&lt;td&gt;29 Oct 2026&lt;/td&gt;
&lt;td&gt;Reasoning-token accounting kept across resume and fork, to avoid premature compaction&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The dates are the dates on &lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex's GitHub releases&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Codex auto compacts at 90% of the model's context window: 244,800 tokens on the 272K models in Codex 0.166.0's bundled catalog, 450,000 on gpt-6.1-terra.&lt;/li&gt;
&lt;li&gt;model_auto_compact_token_limit can only lower that point. To compact later, raise model_context_window, up to the model's maximum (872,000 for most current models).&lt;/li&gt;
&lt;li&gt;There's no setting that turns auto compaction off in Codex 0.166.0. Run /compact yourself at a natural break instead.&lt;/li&gt;
&lt;li&gt;Set model_post_turn_compact_threshold_percent (for example 70) to compact after a finished reply instead of mid-task, where summaries lose the current instruction.&lt;/li&gt;
&lt;li&gt;Keep the task in a file Codex re-reads after compaction; no summary can drop it.&lt;/li&gt;
&lt;li&gt;If compaction starts early after resume, update to 0.166.0; since 0.164.0 a failed compaction no longer leaves a partial summary behind.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  Related
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;Codex auto mode: how to turn on Approve for me, and why it still asks&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;Claude Code keeps compacting: four causes and their fixes&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-compacted-while-idle" rel="noopener noreferrer"&gt;Claude Code "compacted while idle": what it means and how to turn it off&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/why-claude-code-uses-so-many-tokens" rel="noopener noreferrer"&gt;Why Claude Code uses so many tokens&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-crashpad-pending-disk-space" rel="noopener noreferrer"&gt;Codex Crashpad 'pending' eating your Mac's disk&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  When does Codex auto compact?
&lt;/h3&gt;

&lt;p&gt;When the active conversation reaches 90% of the model's context window. In the model catalog bundled with Codex 0.166.0, most models have a 272,000-token window, so auto compaction starts at 244,800 tokens; gpt-6.1-terra has a 500,000-token window, so it starts at 450,000. Codex refreshes that catalog from OpenAI, so the live values can differ. A lower model_auto_compact_token_limit makes it start earlier.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I change the Codex auto compact threshold?
&lt;/h3&gt;

&lt;p&gt;Set model_auto_compact_token_limit in ~/.codex/config.toml to compact earlier. It can only lower the threshold: Codex uses the smaller of your value and 90% of the context window. To compact later, raise model_context_window instead, up to the model's maximum in the catalog (872,000 tokens for most current models in Codex 0.166.0). The 90% rule then applies to the bigger window.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can I disable auto compact in Codex?
&lt;/h3&gt;

&lt;p&gt;No. Codex 0.166.0 has no config key or flag that turns automatic compaction off for your sessions; the code can only disable it internally for certain threads the app server starts. The closest you can get is a later threshold, by raising model_context_window, and compacting at moments you choose with /compact.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I compact manually in Codex?
&lt;/h3&gt;

&lt;p&gt;Type /compact in the CLI and confirm when Codex offers to summarize the chat so far. It replaces earlier turns with a concise summary to free context. /recap is different: it summarizes the conversation for you without compacting the context.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Codex lose my task after compaction?
&lt;/h3&gt;

&lt;p&gt;Because compaction replaces earlier turns with a summary, and a summary written mid-task can drop the current instruction. Several Codex issues report exactly this. Setting model_post_turn_compact_threshold_percent (for example to 70) makes Codex compact after a finished reply instead of in the middle of work, and keeping the task in a file the agent re-reads survives any summary.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Codex compact so early?
&lt;/h3&gt;

&lt;p&gt;Usually because the threshold is lower than the number you're looking at. Auto compaction starts at 90% of the context window, and the window can be smaller than a model's advertised maximum. Codex 0.166.0 also fixed reasoning tokens being counted wrongly after resume or fork, which caused premature compaction, so update first.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does 'Codex ran out of room in the model's context window' mean?
&lt;/h3&gt;

&lt;p&gt;It's Codex's error for a request that no longer fits in the model's context window: 'Codex ran out of room in the model's context window. Start a new thread or clear earlier history before retrying.' Run /compact, or start a new thread and carry the task over in a short written summary.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Codex compaction local or remote?
&lt;/h3&gt;

&lt;p&gt;Both exist. A model provider's remote_compaction capability decides it: v2 sends compaction through the Responses API, and unsupported uses local compaction. Codex counts the two separately in its task.compact telemetry metric, by type remote or local.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/config-file/config-reference" rel="noopener noreferrer"&gt;Configuration reference: model_auto_compact_token_limit, model_context_window, compact_prompt (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developers.openai.com/codex/cli/reference" rel="noopener noreferrer"&gt;Slash commands: /compact and /recap (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/protocol/src/openai_models.rs" rel="noopener noreferrer"&gt;ModelInfo::auto_compact_token_limit, the 90% rule (openai/codex, rust-v0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/core/src/session/context_window.rs" rel="noopener noreferrer"&gt;Context window token status and the hard cap (openai/codex, rust-v0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/models-manager/models.json" rel="noopener noreferrer"&gt;Bundled model catalog, models.json (openai/codex, rust-v0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex releases on GitHub (0.147.0 to 0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@openai/codex" rel="noopener noreferrer"&gt;@openai/codex 0.166.0 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/57608" rel="noopener noreferrer"&gt;Automatic compaction loses active task (openai/codex #57608)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/models-manager/src/manager.rs" rel="noopener noreferrer"&gt;Model catalog cache, models_cache.json (openai/codex manager.rs, rust-v0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/rust-v0.166.0/codex-rs/core/src/compact.rs" rel="noopener noreferrer"&gt;AutoCompactionDisabled (openai/codex compact.rs, rust-v0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/55008" rel="noopener noreferrer"&gt;GPT-6.1 Sol auto-compacts at ~200k despite a displayed 475k window, with a models_cache.json snapshot (openai/codex #55008)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/55126" rel="noopener noreferrer"&gt;Auto-compaction while IDE shows 51% context remaining (openai/codex #55126)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/59534" rel="noopener noreferrer"&gt;Remote compaction v2 can loop (openai/codex #59534)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/4106" rel="noopener noreferrer"&gt;Control over auto-compaction parameters (openai/codex #4106)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-auto-compact" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>openai</category>
    </item>
    <item>
      <title>I Went Looking for Codex Auto Mode. It's Called 'Approve for Me' Now</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Tue, 10 Nov 2026 03:55:39 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-went-looking-for-codex-auto-mode-its-called-approve-for-me-now-376p</link>
      <guid>https://dev.to/its-tahir/i-went-looking-for-codex-auto-mode-its-called-approve-for-me-now-376p</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;I kept seeing people ask where Codex's auto mode is, the way Claude Code has one. It turns out there's no setting by that name: the closest thing is Approve for me (Auto-review), and the old --full-auto flag is gone. I went through the Codex docs, the release notes and the 0.166.0 package to map what each mode actually does. Are you running Codex with a reviewer, or still approving everything yourself?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;OpenAI's Codex (the CLI, the desktop app and the IDE extension) has no setting called "auto mode", as of Codex 0.166.0. What people mean is Approve for me, which the docs also call Auto-review: Codex keeps the same &lt;code&gt;workspace-write&lt;/code&gt; sandbox as its default mode, but when it needs to cross that sandbox, a separate reviewer agent approves or denies the request instead of you. Turn it on with &lt;code&gt;codex --approve-for-me&lt;/code&gt;, with &lt;code&gt;approvals_reviewer = "auto_review"&lt;/code&gt; in &lt;code&gt;~/.codex/config.toml&lt;/code&gt;, or by choosing Approve for me in the permissions control under the composer. The old &lt;code&gt;--full-auto&lt;/code&gt; flag is gone: 0.147.0 removed it from &lt;code&gt;codex exec&lt;/code&gt;, and the 0.166.0 build has no trace of it.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You want&lt;/th&gt;
&lt;th&gt;CLI&lt;/th&gt;
&lt;th&gt;&lt;code&gt;~/.codex/config.toml&lt;/code&gt;&lt;/th&gt;
&lt;th&gt;App or IDE extension&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Codex to approve for you (auto mode)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex --approve-for-me&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;approval_policy = "on-request"&lt;/code&gt; and &lt;code&gt;approvals_reviewer = "auto_review"&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Approve for me&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;To approve things yourself (the default)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;approval_policy = "on-request"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Ask for approval&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Read and plan only&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex --sandbox read-only --ask-for-approval on-request&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sandbox_mode = "read-only"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;n/a (CLI: &lt;code&gt;/permissions&lt;/code&gt; → Read Only)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;No sandbox, no questions&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex --yolo&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sandbox_mode = "danger-full-access"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Full access&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Unattended runs in CI&lt;/td&gt;
&lt;td&gt;&lt;code&gt;codex exec --sandbox workspace-write&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sandbox_mode = "workspace-write"&lt;/code&gt; and &lt;code&gt;approval_policy = "never"&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 5 November 2026, against Codex 0.166.0. Settings and behavior are from OpenAI's Codex docs and the release notes; flag names and on-screen text are quoted from the 0.166.0 Linux package, which I downloaded from npm and searched without running it. I couldn't run a signed-in Codex session for this post, so nothing here claims a first-hand test of the reviewer's decisions.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7o7var9vltzk3vs4fegc.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F7o7var9vltzk3vs4fegc.png" alt="Codex permission modes compared, Codex 0.166.0. Read Only: read-only sandbox, you approve anything beyond it. Ask for approval, the default: workspace-write sandbox, edits and commands in the workspace run, you approve crossing it. Approve for me (Auto-review): same workspace-write sandbox, a reviewer agent approves or denies crossing it, /approve retries once, codex --approve-for-me or approvals_reviewer = auto_review. Full access: no sandbox, nobody asks, --yolo or sandbox_mode = danger-full-access." width="800" height="622"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Approve for me changes who reviews a request to cross the sandbox. It doesn't widen the sandbox or turn on network access.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Is there an auto mode in Codex?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Not by that name, but Approve for me does the job.&lt;/strong&gt; Codex has two separate controls. The sandbox decides what Codex can do on its own (read files, edit the workspace, use the network). The approval policy decides when it has to stop and ask. In the default mode, called Ask for approval in the app and Default in the 0.166.0 CLI picker, Codex edits files and runs commands inside your workspace without asking, and asks you before it crosses that boundary. OpenAI's &lt;a href="https://learn.chatgpt.com/docs/agent-approvals-security" rel="noopener noreferrer"&gt;approvals and security page&lt;/a&gt; calls this same default the &lt;code&gt;Auto&lt;/code&gt; preset, which is part of the confusion: that preset is not Approve for me, because you still answer every request to cross the sandbox.&lt;/p&gt;

&lt;p&gt;Approve for me keeps all of that and changes one thing: who answers. From the &lt;a href="https://learn.chatgpt.com/docs/sandboxing/auto-review" rel="noopener noreferrer"&gt;Auto-review docs&lt;/a&gt;:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;Auto-review replaces manual approval at the sandbox boundary with a separate reviewer agent. The main Codex agent still runs inside the same sandbox, with the same approval policy and the same network and filesystem limits.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;So if you came from Claude Code looking for "auto mode", Approve for me is the equivalent: fewer prompts, with a model checking the risky steps. The difference is in what gets checked, which the comparison below covers.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I turn on auto mode (Approve for me) in Codex?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Use &lt;code&gt;codex --approve-for-me&lt;/code&gt; for one session, &lt;code&gt;/permissions&lt;/code&gt; inside a running session, or &lt;code&gt;approval_policy = "on-request"&lt;/code&gt; plus &lt;code&gt;approvals_reviewer = "auto_review"&lt;/code&gt; in &lt;code&gt;~/.codex/config.toml&lt;/code&gt; to make it your default. In the app or IDE extension, choose Approve for me in the permissions control under the composer, chat by chat.&lt;/strong&gt;&lt;/p&gt;

&lt;h3&gt;
  
  
  In the app or the IDE extension
&lt;/h3&gt;

&lt;p&gt;Open the permissions control below the composer and choose &lt;strong&gt;Approve for me&lt;/strong&gt;. The setting is per chat, so check it's selected in the chat you're working in; the docs warn that "having a mode available doesn't mean it's selected." If it isn't in the list, see Approve for me is missing.&lt;/p&gt;

&lt;h3&gt;
  
  
  In the CLI, for one session
&lt;/h3&gt;

&lt;p&gt;Start Codex with &lt;code&gt;codex --approve-for-me&lt;/code&gt;. The 0.166.0 build describes the flag as:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Route approval requests through automatic review using the workspace-write sandbox
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or, in a running session, type &lt;code&gt;/permissions&lt;/code&gt; and pick Approve for me. Since 0.164.0 you can also do it in one line:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/permissions :workspace --approval-policy=on-request --reviewer=auto_review
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  For every session: config.toml
&lt;/h3&gt;

&lt;p&gt;Add both keys to &lt;code&gt;~/.codex/config.toml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="na"&gt;approval_policy&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"on-request"&lt;/span&gt;
&lt;span class="na"&gt;approvals_reviewer&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"auto_review"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Both matter. The docs are explicit that "changing the approval policy alone doesn't select the reviewer," and the reviewer only runs when approvals are interactive: with &lt;code&gt;approval_policy = "never"&lt;/code&gt;, there is nothing to review. For a one-off run without editing the file, &lt;code&gt;-c approvals_reviewer=auto_review&lt;/code&gt; on the command line does the same, as long as your approval policy is still &lt;code&gt;on-request&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does Approve for me actually review?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Only the actions that would otherwise stop and wait for you.&lt;/strong&gt; Per the &lt;a href="https://learn.chatgpt.com/docs/sandboxing/auto-review" rel="noopener noreferrer"&gt;Auto-review docs&lt;/a&gt;, that means:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;shell or exec calls that ask for escalated sandbox permissions&lt;/li&gt;
&lt;li&gt;network requests the sandbox or policy blocked&lt;/li&gt;
&lt;li&gt;file edits outside the writable folders&lt;/li&gt;
&lt;li&gt;MCP or app tool calls that need approval because of their annotations or your settings&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Everything that already fits inside the sandbox runs without a review step: editing files in the workspace, running your tests, reading the repo. That's why most of a session never reaches the reviewer. Computer Use is an exception: its app approvals still come to you.&lt;/p&gt;

&lt;p&gt;The reviewer is itself a Codex agent. It sees a compact transcript (your messages, Codex's visible updates, relevant tool calls and their output) plus the exact request, but not Codex's hidden reasoning. It's built to block four kinds of action: sending private data or credentials to untrusted places, probing for credentials or tokens, broad or lasting security weakening, and destructive actions that are hard to undo. The full policy is public in the Codex repository as &lt;a href="https://github.com/openai/codex/blob/main/codex-rs/prompts/templates/guardian/policy.md" rel="noopener noreferrer"&gt;policy.md&lt;/a&gt;, and you can replace it with your own text under &lt;code&gt;[auto_review] policy&lt;/code&gt; in &lt;code&gt;config.toml&lt;/code&gt;. If you do, copy the whole default policy first: a custom policy replaces it rather than adding to it.&lt;/p&gt;

&lt;h2&gt;
  
  
  How is Approve for me different from Ask for approval and Full access?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Approve for me and Ask for approval share the same &lt;code&gt;workspace-write&lt;/code&gt; sandbox; the only difference is whether a reviewer agent or you answer requests to cross it. Full access removes the sandbox, so nothing is reviewed at all.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Mode&lt;/th&gt;
&lt;th&gt;Sandbox&lt;/th&gt;
&lt;th&gt;Crossing the sandbox&lt;/th&gt;
&lt;th&gt;Set with&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Read Only&lt;/td&gt;
&lt;td&gt;&lt;code&gt;read-only&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;You approve&lt;/td&gt;
&lt;td&gt;&lt;code&gt;--sandbox read-only&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Ask for approval (default)&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;workspace-write&lt;/code&gt;, network off&lt;/td&gt;
&lt;td&gt;You approve&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;codex&lt;/code&gt;, &lt;code&gt;approval_policy = "on-request"&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Approve for me&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;workspace-write&lt;/code&gt;, network off&lt;/td&gt;
&lt;td&gt;Reviewer agent approves or denies&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;--approve-for-me&lt;/code&gt;, &lt;code&gt;approvals_reviewer = "auto_review"&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Full access&lt;/td&gt;
&lt;td&gt;None&lt;/td&gt;
&lt;td&gt;Nothing is asked&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;--dangerously-bypass-approvals-and-sandbox&lt;/code&gt; (alias &lt;code&gt;--yolo&lt;/code&gt;), &lt;code&gt;sandbox_mode = "danger-full-access"&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The jump from Approve for me to Full access is much bigger than it looks in the menu. Full access removes the sandbox, so there's no boundary left for anything to review. The help text for the flag reads:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Skip all confirmation prompts and execute commands without sandboxing. EXTREMELY DANGEROUS. Intended solely for running in environments that are externally sandboxed
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When you choose full access, Codex 0.166.0 warns that it "can edit any file on your computer and run commands with network, without your approval" and adds: &lt;code&gt;We strongly recommend selecting "Approve for me" instead, and customizing the reviewer policy for your use case.&lt;/code&gt; Keep Full access for containers or VMs you can throw away. That advice isn't Codex-specific: &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;an agent with no sandbox can delete files outside the project&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What happened to --full-auto?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;It was removed in Codex 0.147.0, released on 7 August 2026.&lt;/strong&gt; The &lt;a href="https://github.com/openai/codex/releases/tag/rust-v0.147.0" rel="noopener noreferrer"&gt;release notes&lt;/a&gt; say: "Remove the deprecated &lt;code&gt;codex exec --full-auto&lt;/code&gt; flag; use &lt;code&gt;--sandbox workspace-write&lt;/code&gt; instead." The same release added &lt;code&gt;--approve-for-me&lt;/code&gt;. Neither &lt;code&gt;full-auto&lt;/code&gt; nor &lt;code&gt;full_auto&lt;/code&gt; appears anywhere in the 0.166.0 build, so scripts and guides that still pass it should now stop with an unknown-argument error (I couldn't run Codex to confirm the exact message).&lt;/p&gt;

&lt;p&gt;What to use instead depends on what &lt;code&gt;--full-auto&lt;/code&gt; meant to you:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;"Work in my repo without asking":&lt;/strong&gt; plain &lt;code&gt;codex&lt;/code&gt;, which is already &lt;code&gt;workspace-write&lt;/code&gt; with on-request approvals.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Also stop asking me about the risky steps":&lt;/strong&gt; &lt;code&gt;codex --approve-for-me&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Run unattended in CI":&lt;/strong&gt; &lt;code&gt;codex exec --sandbox workspace-write&lt;/code&gt;. Add &lt;code&gt;--ask-for-approval never&lt;/code&gt; (&lt;code&gt;-a never&lt;/code&gt;) when nothing should wait for a person; failures then go straight back to the model.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two more retirements catch people out. &lt;code&gt;approval_policy = "untrusted"&lt;/code&gt; is no longer supported since 0.149.0, and the docs warn that it "can prevent either client from starting", so remove it from config files and profiles. &lt;code&gt;on-failure&lt;/code&gt; is deprecated. The supported values are &lt;code&gt;on-request&lt;/code&gt;, &lt;code&gt;never&lt;/code&gt; and a granular policy.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does Codex still ask for approval in auto mode?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Either the chat is still in Ask for approval, so you are the reviewer, or the request is outside what Auto-review changes: network access is off by default, folders outside the workspace aren't writable, &lt;code&gt;.git&lt;/code&gt;, &lt;code&gt;.codex&lt;/code&gt;, &lt;code&gt;.agents&lt;/code&gt; and &lt;code&gt;.aws&lt;/code&gt; stay read-only, and Computer Use app approvals always come to you.&lt;/strong&gt; The two cases have different fixes.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;You're actually in the default mode.&lt;/strong&gt; If a prompt such as &lt;code&gt;Would you like to run the following command?&lt;/code&gt; or &lt;code&gt;Would you like to make the following edits?&lt;/code&gt; appears, the reviewer is you. Check the permissions control or the status line for Approve for me. In the app it's set per chat, and &lt;code&gt;approval_policy = "never"&lt;/code&gt; or a granular policy that hides a prompt category means Auto-review never sees those requests.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The request is outside what Approve for me covers.&lt;/strong&gt; Auto-review swaps the reviewer; it doesn't grant anything. These still need a decision or a setting change:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Network access.&lt;/strong&gt; It's off in &lt;code&gt;workspace-write&lt;/code&gt; by default, so every networked command is a crossing. If you trust the repo, turn it on:
&lt;/li&gt;
&lt;/ul&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;  &lt;span class="k"&gt;[sandbox_workspace_write]&lt;/span&gt;
  &lt;span class="na"&gt;network_access&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Files outside the workspace.&lt;/strong&gt; Add the folders you need with &lt;code&gt;--add-dir&lt;/code&gt;, or list them in &lt;code&gt;writable_roots&lt;/code&gt;, instead of approving each write.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Protected paths.&lt;/strong&gt; Inside a writable folder, &lt;code&gt;.git&lt;/code&gt;, &lt;code&gt;.codex&lt;/code&gt;, &lt;code&gt;.agents&lt;/code&gt; and &lt;code&gt;.aws&lt;/code&gt; stay read-only in &lt;code&gt;workspace-write&lt;/code&gt;, so writes there are always crossings.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Destructive MCP and app tools.&lt;/strong&gt; A tool that advertises a destructive annotation always needs approval. In Approve for me that approval goes to the reviewer; in the default mode it comes to you.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Computer Use.&lt;/strong&gt; Its app approvals come to you directly.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;OpenAI's own advice is to fix the boundary instead of training the reviewer to wave things through: add narrow &lt;code&gt;writable_roots&lt;/code&gt; and precise command rules such as &lt;code&gt;["cargo", "test"]&lt;/code&gt; or &lt;code&gt;["pnpm", "run", "lint"]&lt;/code&gt;, and avoid broad ones like &lt;code&gt;["python"]&lt;/code&gt; or &lt;code&gt;["curl"]&lt;/code&gt;, which "often erase the boundary Auto-review is meant to guard."&lt;/p&gt;

&lt;h2&gt;
  
  
  Why did Auto-review deny my command, and how do I override it?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;A denial is deliberate, not an error.&lt;/strong&gt; When the reviewer says no, Codex passes its rationale to the main agent with an instruction not to reach the same goal by a workaround, to continue only with "a materially safer alternative," and otherwise to stop and ask you. If the reviewer gave no reason, the 0.166.0 build shows &lt;code&gt;Auto-reviewer denied the action without a specific rationale.&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;To override one denial in the CLI:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Type &lt;code&gt;/approve&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Pick the action from the &lt;strong&gt;Auto-review Denials&lt;/strong&gt; list. Per the Auto-review docs, Codex keeps up to 10 recent denials per task.&lt;/li&gt;
&lt;li&gt;Confirm. Codex retries that exact action once.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The override is narrow on purpose. It covers that action only, not similar ones later, and the retry still goes through Auto-review, which "can deny again if policy says the user cannot overwrite that class of denial."&lt;/p&gt;

&lt;p&gt;Two limits worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;There's a circuit breaker.&lt;/strong&gt; According to the Auto-review docs, it stops the turn after 3 denials in a row, or 10 denials within the last 50 reviews in the same turn. If a turn ends with a warning after several denials, that's why.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The desktop app has no &lt;code&gt;/approve&lt;/code&gt;.&lt;/strong&gt; As of 5 November 2026, open issues report the reviewer rejecting actions the user had clearly authorized in chat, with no way to override in the app: &lt;a href="https://github.com/openai/codex/issues/58401" rel="noopener noreferrer"&gt;#58401&lt;/a&gt;, &lt;a href="https://github.com/openai/codex/issues/58501" rel="noopener noreferrer"&gt;#58501&lt;/a&gt; and &lt;a href="https://github.com/openai/codex/issues/58855" rel="noopener noreferrer"&gt;#58855&lt;/a&gt;. Until that changes, switch the chat to Ask for approval, approve the one action yourself, and switch back.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why is Approve for me missing or disabled?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Usually an outdated app or CLI, an explicit &lt;code&gt;features.guardian_approval = false&lt;/code&gt; in your effective config, or an admin policy that doesn't allow the &lt;code&gt;auto_review&lt;/code&gt; reviewer. Local settings can't override a managed policy.&lt;/strong&gt; OpenAI's &lt;a href="https://learn.chatgpt.com/docs/reference/troubleshooting" rel="noopener noreferrer"&gt;troubleshooting page&lt;/a&gt; lists three checks:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Update&lt;/strong&gt;, then look at the permissions menu in the chat where you want it. Local and cloud environments can offer different choices.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Check your effective local config&lt;/strong&gt; for an explicit &lt;code&gt;features.guardian_approval = false&lt;/code&gt;, and check the permission profile, approval policy and reviewer you've set.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Ask your admin&lt;/strong&gt; if you're in a managed workspace. Organizations can restrict the allowed permission profiles, sandbox modes, approval policies and reviewers (&lt;code&gt;allowed_approvals_reviewers&lt;/code&gt;), and local settings can't override that.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The app and the CLI can ship different Codex versions, so a mode can appear in one before the other. Run &lt;code&gt;codex --version&lt;/code&gt; for the CLI.&lt;/p&gt;

&lt;h2&gt;
  
  
  Does Approve for me use more tokens?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Yes, it can.&lt;/strong&gt; The &lt;a href="https://learn.chatgpt.com/docs/agent-approvals-security" rel="noopener noreferrer"&gt;approvals and security docs&lt;/a&gt; say plainly that "automatic review uses extra model calls, so it can add to Codex usage." The reviewer only runs for actions that already need approval, so the extra cost tracks how often your work crosses the sandbox, not how many commands Codex runs. A session that installs packages and calls APIs all day will pay for more reviews than one that edits and tests inside the repo. Turning on network access for a repo you trust removes most of those crossings. To put a figure on a session, plug its token counts into &lt;a href="https://tools.its-tahir.com/llm-cost-calculator" rel="noopener noreferrer"&gt;an LLM cost calculator&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is Codex auto mode the same as Claude Code auto mode?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Same goal, different design.&lt;/strong&gt; Both cut prompts by letting a second model judge risky steps. They draw the line in different places.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Codex Approve for me&lt;/th&gt;
&lt;th&gt;Claude Code auto mode&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;What runs without review&lt;/td&gt;
&lt;td&gt;Anything the OS sandbox allows: workspace edits and commands&lt;/td&gt;
&lt;td&gt;Reads and file edits in your working directory&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;What the reviewer checks&lt;/td&gt;
&lt;td&gt;Only requests to cross the sandbox&lt;/td&gt;
&lt;td&gt;Shell commands, network calls and other actions&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Main safety line&lt;/td&gt;
&lt;td&gt;OS-enforced sandbox (Seatbelt on macOS, bwrap on Linux, MXC on Windows)&lt;/td&gt;
&lt;td&gt;The classifier, with an optional sandbox&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Starting mode&lt;/td&gt;
&lt;td&gt;Ask for approval (you review)&lt;/td&gt;
&lt;td&gt;Auto mode, since Claude Code 2.1.283 (2.1.284 for every account)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Fix a false block&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/approve&lt;/code&gt; in the CLI for one retry; narrow command rules&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/auto-mode-setup&lt;/code&gt;, or &lt;code&gt;autoMode.environment&lt;/code&gt; and &lt;code&gt;autoMode.allow&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Turn it on&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;--approve-for-me&lt;/code&gt; or &lt;code&gt;approvals_reviewer = "auto_review"&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Shift+Tab, or &lt;code&gt;"defaultMode": "auto"&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;In practice, Codex's sandbox does most of the work and the reviewer handles the exceptions, while Claude Code's classifier sees most commands. If you use both, the Claude side is covered in &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode" rel="noopener noreferrer"&gt;Claude Code auto mode is now the default&lt;/a&gt;, and how Claude Code's optional sandbox compares is in &lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;the Claude Code sandbox guide&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changed in Codex approvals recently?
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Between 0.146.1 and 0.166.0 (August to October 2026), Codex added &lt;code&gt;--approve-for-me&lt;/code&gt;, removed &lt;code&gt;--full-auto&lt;/code&gt;, retired the &lt;code&gt;untrusted&lt;/code&gt; policy and let &lt;code&gt;/permissions&lt;/code&gt; set the reviewer inline.&lt;/strong&gt;&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Date&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;0.146.1&lt;/td&gt;
&lt;td&gt;5 Aug 2026&lt;/td&gt;
&lt;td&gt;Safer Auto-review defaults for cyber models backported&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.147.0&lt;/td&gt;
&lt;td&gt;7 Aug 2026&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;--approve-for-me&lt;/code&gt; flag added; &lt;code&gt;codex exec --full-auto&lt;/code&gt; removed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.148.0&lt;/td&gt;
&lt;td&gt;18 Aug 2026&lt;/td&gt;
&lt;td&gt;Strict Auto-review enforced for MCP tool calls; Auto-review state included in turn metadata&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.149.0&lt;/td&gt;
&lt;td&gt;20 Aug 2026&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;untrusted&lt;/code&gt; approval policy retired&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.164.0&lt;/td&gt;
&lt;td&gt;23 Oct 2026&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/permissions&lt;/code&gt; accepts a profile, approval policy and reviewer inline&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;0.166.0&lt;/td&gt;
&lt;td&gt;29 Oct 2026&lt;/td&gt;
&lt;td&gt;The CLI respects server approval-policy defaults at startup&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The dates are the dates on &lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex's GitHub releases&lt;/a&gt;. One more change sits outside the table: per the Auto-review docs, choosing an approved Daybreak (cyber) model in the app switches the chat to Approve for me, and the 0.166.0 build explains it with &lt;code&gt;Cyber models default to "Approve for me" for safety reasons.&lt;/code&gt;&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Codex has no 'auto mode' setting. The equivalent is Approve for me (Auto-review): the default workspace-write sandbox, with a reviewer agent answering approval requests instead of you.&lt;/li&gt;
&lt;li&gt;Turn it on with codex --approve-for-me, /permissions, or approval_policy = "on-request" plus approvals_reviewer = "auto_review" in ~/.codex/config.toml.&lt;/li&gt;
&lt;li&gt;Auto-review only checks requests to cross the sandbox. It doesn't turn on network access, add writable folders or unlock .git, .codex, .agents and .aws.&lt;/li&gt;
&lt;li&gt;--full-auto was removed in Codex 0.147.0. Use plain codex, --approve-for-me, or codex exec --sandbox workspace-write for CI.&lt;/li&gt;
&lt;li&gt;Override a denial once with /approve in the CLI. The app has no /approve, so switch that chat to Ask for approval for the one action.&lt;/li&gt;
&lt;li&gt;Full access (--yolo) removes the sandbox and every check. Keep it for containers and VMs you can throw away.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  Related
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode" rel="noopener noreferrer"&gt;Claude Code auto mode is now the default: turn it off, or keep it&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;The Claude Code sandbox: what it blocks and how to set it up&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;Claude Code deleted my files: what happened and how to stop it&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-auto-compact" rel="noopener noreferrer"&gt;Codex auto compact: when it triggers, and how to control it&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.its-tahir.com/blog/codex-crashpad-pending-disk-space" rel="noopener noreferrer"&gt;Codex Crashpad 'pending' eating your Mac's disk&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Is there an auto mode in Codex?
&lt;/h3&gt;

&lt;p&gt;Not under that name. The closest is Approve for me, also called Auto-review. Codex keeps the same workspace-write sandbox as its default Ask for approval mode, but when it needs to cross that sandbox (network access, files outside the workspace, an escalated command), a separate reviewer agent approves or denies the request instead of you. Turn it on with codex --approve-for-me, approvals_reviewer = "auto_review" in config.toml, or Approve for me in the app's permissions control.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I turn on Approve for me in the Codex CLI?
&lt;/h3&gt;

&lt;p&gt;For one session, start Codex with codex --approve-for-me, or type /permissions and pick Approve for me. To make it the default, add approval_policy = "on-request" and approvals_reviewer = "auto_review" to ~/.codex/config.toml. Changing the approval policy alone doesn't select the reviewer, and with approval_policy = "never" there is nothing left to review.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the difference between Approve for me and Full access in Codex?
&lt;/h3&gt;

&lt;p&gt;Approve for me keeps the sandbox: Codex can edit and run commands inside the workspace, and a reviewer agent checks every request to go beyond it. Full access removes the sandbox and the approvals entirely (sandbox_mode = "danger-full-access", or --dangerously-bypass-approvals-and-sandbox, alias --yolo), so nothing is checked. OpenAI recommends Full access only inside an environment that is already isolated, such as a container.&lt;/p&gt;

&lt;h3&gt;
  
  
  What happened to codex --full-auto?
&lt;/h3&gt;

&lt;p&gt;It's gone. Codex 0.147.0 (7 August 2026) removed the deprecated codex exec --full-auto flag and said to use --sandbox workspace-write instead, and the same release added --approve-for-me. The 0.166.0 build contains neither full-auto nor full_auto. For an interactive equivalent of the old behavior, plain codex already runs workspace-write with on-request approvals.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Codex still ask for approval?
&lt;/h3&gt;

&lt;p&gt;Because the request crosses the sandbox and the reviewer is still you. In the default mode Codex asks before network access (off by default in workspace-write), before editing files outside the workspace, and before running commands that need escalation. Turn on Approve for me to hand those to the reviewer, enable network with [sandbox_workspace_write] network_access = true, or add folders with --add-dir. Writes to .git, .codex, .agents and .aws inside the workspace stay read-only either way.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I override an Auto-review denial in Codex?
&lt;/h3&gt;

&lt;p&gt;In the CLI, type /approve, pick the denied action from the Auto-review Denials list, and confirm. Codex retries that exact action once, and the retry still goes through Auto-review, which can deny it again if policy says users can't override that kind of denial. The desktop app has no /approve; switch the chat to Ask for approval and approve the action yourself.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why is Approve for me missing or disabled in Codex?
&lt;/h3&gt;

&lt;p&gt;Usually one of three things: an older app or CLI version, an explicit features.guardian_approval = false in your effective configuration, or an organization policy that doesn't allow the auto_review reviewer, the workspace-write sandbox or on-request approvals. Local settings can't override managed requirements. The app and CLI can also bundle different Codex versions, so check both with codex --version.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does Approve for me use more tokens?
&lt;/h3&gt;

&lt;p&gt;Yes, it can. OpenAI's docs say automatic review uses extra model calls, so it can add to Codex usage. Reviews only run for actions that already need approval, so the cost depends on how often your work crosses the sandbox, not on how many commands Codex runs inside it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/agent-approvals-security" rel="noopener noreferrer"&gt;Agent approvals &amp;amp; security (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/sandboxing/auto-review" rel="noopener noreferrer"&gt;Auto-review (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/permission-modes" rel="noopener noreferrer"&gt;Permissions (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/config-file/config-reference" rel="noopener noreferrer"&gt;Configuration reference (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://developers.openai.com/codex/cli/reference" rel="noopener noreferrer"&gt;Developer commands: /permissions and /approve (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://learn.chatgpt.com/docs/reference/troubleshooting" rel="noopener noreferrer"&gt;Troubleshooting: Approve for me is missing or disabled (Codex docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/releases/tag/rust-v0.147.0" rel="noopener noreferrer"&gt;Codex 0.147.0 release notes (--approve-for-me added, --full-auto removed)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@openai/codex" rel="noopener noreferrer"&gt;@openai/codex 0.166.0 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/issues/58401" rel="noopener noreferrer"&gt;Approval review treats direct user authorization as untrusted transcript (openai/codex #58401)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/releases" rel="noopener noreferrer"&gt;Codex releases on GitHub (0.146.1 to 0.166.0)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/main/codex-rs/prompts/templates/guardian/policy.md" rel="noopener noreferrer"&gt;Default Auto-review policy (codex-rs/prompts/templates/guardian/policy.md)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/codex-auto-mode" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>openai</category>
    </item>
    <item>
      <title>Claude Code Keeps Saying 'Not Logged In · Please Run /login'? I Mapped Every Login Message in 2.1.318</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Sun, 08 Nov 2026 20:55:51 +0000</pubDate>
      <link>https://dev.to/its-tahir/claude-code-keeps-saying-not-logged-in-please-run-login-i-mapped-every-login-message-in-395o</link>
      <guid>https://dev.to/its-tahir/claude-code-keeps-saying-not-logged-in-please-run-login-i-mapped-every-login-message-in-395o</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;I kept seeing two different login errors in Claude Code and assumed they meant the same thing. They don't: one means there is no credential at all, the other means Claude Code tried to renew my login and gave up. Version 2.1.318 also adds a third, for a login that hits a fixed end date. Which one have you been hitting, and how often?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Code shows &lt;code&gt;Not logged in · Please run /login&lt;/code&gt; when the session has no credential it can use, and &lt;code&gt;Login expired · Please run /login&lt;/code&gt; when it tried to renew your saved claude.ai login, the renewal was refused, and it cleared the login. Both are fixed the same way: run &lt;code&gt;/login&lt;/code&gt; inside Claude Code, or &lt;code&gt;claude auth login&lt;/code&gt; in a shell.&lt;/strong&gt; Retrying without signing in shows the same message on every request. Since Claude Code 2.1.318 there is a third message, &lt;code&gt;Login reached its time limit · Please run /login&lt;/code&gt;, for a login that hit its fixed end date; renewing early doesn't move that date, and for unattended jobs the fix is &lt;code&gt;claude setup-token&lt;/code&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You see&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Not logged in · Please run /login&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No saved login, API key or token this session can use&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/login&lt;/code&gt;, or check &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; and &lt;code&gt;CLAUDE_CONFIG_DIR&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Login expired · Please run /login&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Renewing your claude.ai login was refused, so the login was cleared&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/login&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;Login reached its time limit · Please run /login&lt;/code&gt; (2.1.318+)&lt;/td&gt;
&lt;td&gt;The login reached its fixed end date&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude auth login&lt;/code&gt;; &lt;code&gt;claude setup-token&lt;/code&gt; for jobs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Your login expires in 3 days · run /login to renew&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A warning; requests keep working until then&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/login&lt;/code&gt; before the date&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OAuth token revoked · Please run /login&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The API rejected the token Claude Code sent&lt;/td&gt;
&lt;td&gt;&lt;code&gt;/login&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Could not refresh your login because another Claude Code process is refreshing it…&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Not a rejection: another process holds the refresh lock&lt;/td&gt;
&lt;td&gt;Wait a minute, or close other windows&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Authentication required · Sign in again to continue&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;The Not logged in state, in a Claude Desktop session&lt;/td&gt;
&lt;td&gt;Sign in again from the app&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Remote Control disconnected — Claude.ai login expired — run /login …&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your login expired or was rejected during Remote Control&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/login&lt;/code&gt;, then &lt;code&gt;/remote-control&lt;/code&gt; if the message says so&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Failed to authenticate: OAuth session expired and could not be refreshed&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Login expired, in &lt;code&gt;claude -p&lt;/code&gt; or the Agent SDK&lt;/td&gt;
&lt;td&gt;Run &lt;code&gt;claude&lt;/code&gt;, complete &lt;code&gt;/login&lt;/code&gt;, rerun&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 4 November 2026, against Claude Code 2.1.318. I reproduced &lt;code&gt;Not logged in · Please run /login&lt;/code&gt; on Windows 11 with Claude Code 2.1.161 by pointing &lt;code&gt;CLAUDE_CONFIG_DIR&lt;/code&gt; at an empty folder. The 2.1.318 messages are quoted from the Linux build, which I downloaded from npm into a throwaway folder and searched without running it. Everything else comes from Anthropic's authentication docs, error reference and changelog, linked at each point.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhwiw6xj9bkw8g72jtiz2.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fhwiw6xj9bkw8g72jtiz2.png" alt="Claude Code login messages and fixes. Not logged in · Please run /login: no credential this session can use; run /login or check ANTHROPIC_API_KEY. Login expired · Please run /login: renewal of the claude.ai login was refused and the login was cleared; run /login. Login reached its time limit · Please run /login (2.1.318): the login hit its fixed end date; run claude auth login, or claude setup-token for unattended jobs. Your login expires in 3 days · run /login to renew: a warning only. OAuth token revoked · Please run /login: the API rejected the token; run /login. Could not refresh your login because another Claude Code process is refreshing it: wait a minute or close other windows." width="800" height="711"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Six of the sign-in messages, one question each: is there a credential, can it still be renewed, and who rejected it.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "Not logged in · Please run /login" mean?
&lt;/h2&gt;

&lt;p&gt;It means Claude Code found no credential it can use for this session. The &lt;a href="https://code.claude.com/docs/en/errors#not-logged-in" rel="noopener noreferrer"&gt;error reference&lt;/a&gt; puts it in one line: "No valid credential is available for this session." Nothing was rejected; there was simply nothing to send.&lt;/p&gt;

&lt;p&gt;You can reproduce it in under a minute, which is a good way to see what "no credential" looks like. With a fresh, empty config folder and no key in the environment:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nv"&gt;CLAUDE_CONFIG_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/tmp/empty-claude claude &lt;span class="nt"&gt;-p&lt;/span&gt; &lt;span class="s2"&gt;"hi"&lt;/span&gt;
&lt;span class="c"&gt;# Not logged in · Please run /login     (exit code 1)&lt;/span&gt;

&lt;span class="nv"&gt;CLAUDE_CONFIG_DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;/tmp/empty-claude claude auth status
&lt;span class="c"&gt;# output from 2.1.161; 2.1.268+ also prints configDirectory, 2.1.318+ loginExpiresAt&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"loggedIn"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"authMethod"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"none"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"apiProvider"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"firstParty"&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;claude auth status&lt;/code&gt; exits with code 1 when you're signed out and 0 when you're signed in, so scripts can check it before they start a job.&lt;/p&gt;

&lt;p&gt;The usual reasons you land here without meaning to:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A different config folder.&lt;/strong&gt; Each &lt;code&gt;CLAUDE_CONFIG_DIR&lt;/code&gt; keeps its own login. An alias like &lt;code&gt;claude-work&lt;/code&gt; that sets it starts signed out until you log in once there.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An API key that isn't reaching Claude Code.&lt;/strong&gt; &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; has to be exported in the shell that launches &lt;code&gt;claude&lt;/code&gt;. In interactive mode Claude Code also asks once whether to use the key; if you declined, it stays unused until you flip the &lt;strong&gt;Use custom API key&lt;/strong&gt; toggle in &lt;code&gt;/config&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A background or cloud worker.&lt;/strong&gt; The key or token has to be in the environment that starts the worker, not just in your terminal.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A damaged saved login.&lt;/strong&gt; If the stored &lt;code&gt;/login&lt;/code&gt; credential contains a character an HTTP header can't carry, Claude Code reports it as Not logged in. Run &lt;code&gt;/login&lt;/code&gt; to save a fresh one.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;In a session the Claude Desktop app runs, such as the Code tab or Cowork, the same state reads &lt;code&gt;Authentication required · Sign in again to continue&lt;/code&gt;, and you sign in again from the app.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If you just logged in somewhere else:&lt;/strong&gt; signing in with claude.ai in another Claude Code window that uses the same config folder fixes an open interactive session on its own; you don't need to restart it. On macOS before 2.1.286, you had to restart the session. Before 2.1.318, running jobs could also exit with &lt;code&gt;Not logged in&lt;/code&gt; when another terminal or host signed in again to the same account.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "Login expired · Please run /login" mean?
&lt;/h2&gt;

&lt;p&gt;It means Claude Code tried to renew your saved claude.ai login, the sign-in service rejected the stored refresh token, and Claude Code cleared the saved credentials. From then on, &lt;a href="https://code.claude.com/docs/en/errors#login-expired" rel="noopener noreferrer"&gt;per the docs&lt;/a&gt;, "each model request stops locally with this message before it reaches the API, because only &lt;code&gt;/login&lt;/code&gt; can create new credentials."&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Login expired · Please run /login
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In non-interactive mode (&lt;code&gt;claude -p&lt;/code&gt;) and the Agent SDK, the same state reads differently, with the structured error code &lt;code&gt;authentication_failed&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Failed to authenticate: OAuth session expired and could not be refreshed
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three things worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It is not the same as &lt;code&gt;OAuth token revoked&lt;/code&gt;.&lt;/strong&gt; That message reports a rejection the API returned. &lt;code&gt;Login expired&lt;/code&gt; is Claude Code's own verdict on a login it already failed to renew, so no request is sent at all.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Only a saved claude.ai login can expire this way.&lt;/strong&gt; Sessions using an API key, &lt;code&gt;CLAUDE_CODE_OAUTH_TOKEN&lt;/code&gt; or a cloud provider never see it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Before 2.1.206 it looked like something else.&lt;/strong&gt; Claude Code sent the request anyway with whatever credential was left, and every model failed with &lt;a href="https://www.its-tahir.com/blog/claude-code-issue-with-the-selected-model" rel="noopener noreferrer"&gt;There's an issue with the selected model&lt;/a&gt; or a 401. If you're on an old build and every model suddenly fails, check your login first.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The fix is &lt;code&gt;/login&lt;/code&gt;. In a script, run &lt;code&gt;claude&lt;/code&gt; once in the same environment, complete &lt;code&gt;/login&lt;/code&gt;, then rerun your command.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is "Login reached its time limit"?
&lt;/h2&gt;

&lt;p&gt;It is a new message in Claude Code 2.1.318 for a claude.ai login that has reached its fixed end date. The changelog describes the change as fixing "the sign-in failure when a stored claude.ai login reaches its time limit: it now says so." In the 2.1.318 build the interactive form is:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Login reached its time limit · Please run /login
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;and in &lt;code&gt;claude -p&lt;/code&gt; it names the two ways out:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Failed to authenticate: this login reached its time limit and cannot be renewed. Run `claude auth login` to sign in again, or use `claude setup-token` and set CLAUDE_CODE_OAUTH_TOKEN for unattended jobs
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The important word is &lt;em&gt;cannot be renewed&lt;/em&gt;. Claude Code refreshes your login in the background as you work, but that refresh doesn't extend the end date. Only a new sign-in does. Anthropic's docs don't state how long a claude.ai login lasts, so I won't guess; check yours with &lt;code&gt;claude auth status&lt;/code&gt;, below.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I check when my Claude Code login expires?
&lt;/h2&gt;

&lt;p&gt;Run &lt;code&gt;claude auth status&lt;/code&gt; on 2.1.318 or later. Its JSON now includes &lt;code&gt;loginExpiresAt&lt;/code&gt;, the date your stored claude.ai sign-in ends (it's &lt;code&gt;null&lt;/code&gt; when no such login is in use):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude auth status
claude auth status &lt;span class="nt"&gt;--text&lt;/span&gt;   &lt;span class="c"&gt;# human-readable&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There are three other places the date shows up:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;claude -p&lt;/code&gt; text output&lt;/strong&gt; prints a one-line warning on stderr, starting 10 days before a stored claude.ai sign-in ends. In the 2.1.318 build it reads &lt;code&gt;Warning: this sign-in ends between &amp;lt;date&amp;gt; and &amp;lt;date&amp;gt; (in N days at the earliest). Renewing it does not move those dates. Run claude auth login before then, or use claude setup-token for unattended jobs.&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;claude -p --output-format json&lt;/code&gt; results&lt;/strong&gt; carry &lt;code&gt;credential_expires_at&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Interactive sessions&lt;/strong&gt; warn at startup when the login is within three days of expiring: &lt;code&gt;Your login expires in 3 days · run /login to renew&lt;/code&gt;. The &lt;a href="https://code.claude.com/docs/en/authentication#renew-an-expiring-login" rel="noopener noreferrer"&gt;authentication docs&lt;/a&gt; are clear that this "is informational and never blocks a request."&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Once a login can't be renewed, &lt;code&gt;/status&lt;/code&gt; shows a &lt;code&gt;Login&lt;/code&gt; row reading &lt;code&gt;Expired — log in again&lt;/code&gt; with the organization and email it had saved (2.1.210 or later). That row appears only when the saved claude.ai login is the active credential.&lt;/p&gt;

&lt;p&gt;Renewing early matters most for sessions nobody is watching. The docs warn that a background session or a Remote Control session that outlives the login "stops making progress once the credential expires and can't recover until you sign in again."&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does Claude Code keep logging me out?
&lt;/h2&gt;

&lt;p&gt;Most repeated sign-outs come from one of a handful of causes, and several of them were bugs that are now fixed. Run &lt;code&gt;claude update&lt;/code&gt; first:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Cause&lt;/th&gt;
&lt;th&gt;Fixed in&lt;/th&gt;
&lt;th&gt;What to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;System clock is off (token checks depend on the time)&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;Sync your clock, then &lt;code&gt;/login&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Two sessions renewed with the same token after the machine woke from sleep&lt;/td&gt;
&lt;td&gt;2.1.211&lt;/td&gt;
&lt;td&gt;Update&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;An older build, such as an IDE extension's bundled CLI, ran on the same machine&lt;/td&gt;
&lt;td&gt;2.1.277&lt;/td&gt;
&lt;td&gt;Update both&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A short command (&lt;code&gt;claude auth status&lt;/code&gt;, &lt;code&gt;claude plugin list&lt;/code&gt;) exited mid-refresh&lt;/td&gt;
&lt;td&gt;2.1.301, 2.1.317&lt;/td&gt;
&lt;td&gt;Update&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Another terminal or host signed in again to the same account, and running jobs exited with &lt;code&gt;Not logged in&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;2.1.318&lt;/td&gt;
&lt;td&gt;Update&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;macOS login keychain locked (SSH, sleep) or out of sync with your password&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude doctor&lt;/code&gt;, then unlock the keychain&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; from a disabled organization overrides your subscription&lt;/td&gt;
&lt;td&gt;n/a&lt;/td&gt;
&lt;td&gt;Unset it; check &lt;code&gt;/status&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;If you use many parallel sessions, you may also see &lt;code&gt;Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh)&lt;/code&gt;. That one isn't a rejection: your login needed renewing and another process held the shared refresh lock. Wait a minute; if it keeps coming back, close the other windows, and if no other Claude Code process is running, &lt;code&gt;/login&lt;/code&gt; skips the lock.&lt;/p&gt;

&lt;p&gt;On macOS, when the keychain refuses the write, Claude Code saves your login to the plain-text &lt;code&gt;~/.claude/.credentials.json&lt;/code&gt; instead. The &lt;a href="https://code.claude.com/docs/en/troubleshoot-install#not-logged-in-or-token-expired" rel="noopener noreferrer"&gt;troubleshooting docs&lt;/a&gt; walk through moving it back: run &lt;code&gt;claude doctor&lt;/code&gt;, unlock with &lt;code&gt;security unlock-keychain ~/Library/Keychains/login.keychain-db&lt;/code&gt;, then &lt;code&gt;/logout&lt;/code&gt; and &lt;code&gt;/login&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I log in again?
&lt;/h2&gt;

&lt;p&gt;Run &lt;code&gt;/login&lt;/code&gt; inside Claude Code, or &lt;code&gt;claude auth login&lt;/code&gt; from a shell. A browser window opens; if it doesn't, press &lt;code&gt;c&lt;/code&gt; to copy the login URL and paste it into a browser yourself. If the browser shows a code instead of returning to the terminal, paste it at the &lt;code&gt;Paste code here if prompted&lt;/code&gt; prompt. The terminal shows &lt;code&gt;Login successful&lt;/code&gt; when it's done.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;claude auth login&lt;/code&gt; takes a few options from the &lt;a href="https://code.claude.com/docs/en/cli-reference" rel="noopener noreferrer"&gt;CLI reference&lt;/a&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude auth login &lt;span class="nt"&gt;--console&lt;/span&gt;          &lt;span class="c"&gt;# Anthropic Console (API billing) instead of a subscription&lt;/span&gt;
claude auth login &lt;span class="nt"&gt;--sso&lt;/span&gt;              &lt;span class="c"&gt;# force SSO&lt;/span&gt;
claude auth login &lt;span class="nt"&gt;--email&lt;/span&gt; you@work.com
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If sign-in keeps failing with an SSL error such as &lt;code&gt;OAuth error: SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY)&lt;/code&gt;, the problem is your network, not your account: see &lt;a href="https://www.its-tahir.com/blog/claude-code-ssl-certificate-corporate-proxy" rel="noopener noreferrer"&gt;the SSL certificate fix&lt;/a&gt;. If an invalid or rejected code is the problem, the &lt;a href="https://tools.its-tahir.com/errors/oauth-error-invalid-code" rel="noopener noreferrer"&gt;OAuth error: invalid code&lt;/a&gt; page covers it.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I log out of Claude Code?
&lt;/h2&gt;

&lt;p&gt;Type &lt;code&gt;/logout&lt;/code&gt; at the Claude Code prompt, or run &lt;code&gt;claude auth logout&lt;/code&gt; in a shell. Logging out does more than you might expect: it removes all stored credentials, including saved MCP server logins and plugin secrets, and resets first-launch setup, so the next &lt;code&gt;claude&lt;/code&gt; run walks you through login and setup again. Expect to re-authorize your MCP servers afterwards.&lt;/p&gt;

&lt;p&gt;To keep two accounts signed in at once, such as work and personal, don't log out and in; give each its own config folder:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;alias &lt;/span&gt;claude-work&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'CLAUDE_CONFIG_DIR=~/.claude-work claude'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  How do I stay logged in for CI and scripts?
&lt;/h2&gt;

&lt;p&gt;Use &lt;code&gt;claude setup-token&lt;/code&gt;. It runs the same browser sign-in as &lt;code&gt;/login&lt;/code&gt;, then prints a one-year OAuth token to the terminal without saving it anywhere. Set it as &lt;code&gt;CLAUDE_CODE_OAUTH_TOKEN&lt;/code&gt; wherever the job runs:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;CLAUDE_CODE_OAUTH_TOKEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;your-token        &lt;span class="c"&gt;# macOS, Linux, WSL&lt;/span&gt;
&lt;span class="nv"&gt;$env&lt;/span&gt;:CLAUDE_CODE_OAUTH_TOKEN &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"your-token"&lt;/span&gt;      &lt;span class="c"&gt;# Windows PowerShell&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Its limits, from the &lt;a href="https://code.claude.com/docs/en/authentication#generate-a-long-lived-token" rel="noopener noreferrer"&gt;authentication docs&lt;/a&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;It needs a Pro, Max, Ultra, Team or Enterprise plan.&lt;/li&gt;
&lt;li&gt;It can only make model requests, so it can't start Remote Control sessions or fetch claude.ai connectors. Locally configured MCP servers still work.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;--bare&lt;/code&gt; mode doesn't read it; use &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; or an &lt;code&gt;apiKeyHelper&lt;/code&gt; there.&lt;/li&gt;
&lt;li&gt;Treat it like a password. Anyone who has it can spend your subscription, so keep it in your CI's secret store, never in a repository.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you run &lt;code&gt;/login&lt;/code&gt; while the variable is set, the current session switches to the new login. To keep that login in new sessions, remove the variable from your shell profile and settings files.&lt;/p&gt;

&lt;p&gt;For billing on the API instead of a subscription, an &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; from the Console works in scripts too; the &lt;a href="https://tools.its-tahir.com/api-key-checker" rel="noopener noreferrer"&gt;API key checker&lt;/a&gt; tells you whether a key is valid before you wire it in.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which credential is Claude Code actually using?
&lt;/h2&gt;

&lt;p&gt;When several are present, Claude Code picks the first of these, per the &lt;a href="https://code.claude.com/docs/en/authentication#authentication-precedence" rel="noopener noreferrer"&gt;authentication precedence&lt;/a&gt; list:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Cloud provider credentials (&lt;code&gt;CLAUDE_CODE_USE_BEDROCK&lt;/code&gt;, &lt;code&gt;_VERTEX&lt;/code&gt;, &lt;code&gt;_FOUNDRY&lt;/code&gt;)&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ANTHROPIC_AUTH_TOKEN&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; (in &lt;code&gt;-p&lt;/code&gt;, always used when present)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;apiKeyHelper&lt;/code&gt; output&lt;/li&gt;
&lt;li&gt;&lt;code&gt;CLAUDE_CODE_OAUTH_TOKEN&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Anthropic profile and federation credentials&lt;/li&gt;
&lt;li&gt;Your &lt;code&gt;/login&lt;/code&gt; subscription credentials&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;This is why a stale key in a &lt;code&gt;.env&lt;/code&gt; file can make a working subscription look broken: the key wins. Run &lt;code&gt;/status&lt;/code&gt; to see the active credential; when a login and a key are both configured, it marks the one not in use. For a key that's rejected, see &lt;a href="https://tools.its-tahir.com/errors/invalid-api-key" rel="noopener noreferrer"&gt;Invalid API key&lt;/a&gt; and &lt;a href="https://tools.its-tahir.com/errors/api-error-401" rel="noopener noreferrer"&gt;API Error 401&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changed in Claude Code sign-in recently?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.206&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;Login expired · Please run /login&lt;/code&gt; replaces the misleading "issue with the selected model" and 401 errors after a failed renewal&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.210&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/status&lt;/code&gt; shows &lt;code&gt;Login: Expired — log in again&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.211&lt;/td&gt;
&lt;td&gt;Waking from sleep no longer makes two sessions revoke the shared login&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.268&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude auth status&lt;/code&gt; JSON adds &lt;code&gt;configDirectory&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.277&lt;/td&gt;
&lt;td&gt;An older build on the same machine no longer logs you out&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.286&lt;/td&gt;
&lt;td&gt;macOS sessions pick up a login made in another window&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.301&lt;/td&gt;
&lt;td&gt;Short commands exiting mid-refresh no longer sign you out&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.317&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude auth status&lt;/code&gt; waits for a slow token refresh to be saved&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.318&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;loginExpiresAt&lt;/code&gt; in &lt;code&gt;claude auth status&lt;/code&gt;, &lt;code&gt;credential_expires_at&lt;/code&gt; in &lt;code&gt;-p&lt;/code&gt; JSON, a 10-day stderr warning in &lt;code&gt;-p&lt;/code&gt;, the &lt;code&gt;Login reached its time limit&lt;/code&gt; message, and no more &lt;code&gt;Not logged in&lt;/code&gt; when another terminal signs in again&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Not logged in · Please run /login means no usable credential at all; Login expired · Please run /login means renewing your claude.ai login failed and Claude Code cleared it. Both are fixed with /login.&lt;/li&gt;
&lt;li&gt;Retrying never fixes Login expired: the request stops locally before reaching the API.&lt;/li&gt;
&lt;li&gt;Login reached its time limit (2.1.318+) is a fixed end date. Background renewal doesn't move it; a new claude auth login does.&lt;/li&gt;
&lt;li&gt;claude auth status shows loginExpiresAt on 2.1.318+, and exits 1 when you're signed out, so scripts can check it first.&lt;/li&gt;
&lt;li&gt;Repeated sign-outs were mostly bugs fixed between 2.1.211 and 2.1.318. Update, check your clock, and on macOS check the keychain with claude doctor.&lt;/li&gt;
&lt;li&gt;For CI and scripts, claude setup-token prints a one-year token for CLAUDE_CODE_OAUTH_TOKEN. Keep it in a secret store.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h2&gt;
  
  
  Related errors
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;If you're seeing&lt;/th&gt;
&lt;th&gt;Read&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OAuth error: SSL certificate error&lt;/code&gt; during &lt;code&gt;/login&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-ssl-certificate-corporate-proxy" rel="noopener noreferrer"&gt;Claude Code SSL certificate verification failed&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;There's an issue with the selected model&lt;/code&gt; on every model&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-issue-with-the-selected-model" rel="noopener noreferrer"&gt;It's usually a 404, or an expired login on an old build&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Signing in to Claude Code inside a Docker container&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;Running Claude Code in a sandbox or Docker&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sessions suddenly starting in &lt;code&gt;⏵⏵ auto mode on&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode" rel="noopener noreferrer"&gt;Claude Code auto mode: on, off or default&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For anything not listed here, &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;the full list of Claude Code errors and fixes&lt;/a&gt; groups every error I've written up by cause.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What does 'Not logged in · Please run /login' mean in Claude Code?
&lt;/h3&gt;

&lt;p&gt;The session has no credential it can use: no saved claude.ai or Console login, no API key, no token. Common causes are a first run, a different CLAUDE_CONFIG_DIR (each config folder has its own login), an ANTHROPIC_API_KEY that is set but not exported to the shell that started claude, or a saved login that was damaged. Run /login, or claude auth login from a shell, then check with claude auth status.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does 'Login expired · Please run /login' mean?
&lt;/h3&gt;

&lt;p&gt;Claude Code tried to renew your saved claude.ai login, the sign-in service refused the stored refresh token, and Claude Code cleared the saved login. Every request after that stops locally with this message, so retrying never helps: run /login. In claude -p and the Agent SDK the same state reads 'Failed to authenticate: OAuth session expired and could not be refreshed'. Sessions that use an API key, CLAUDE_CODE_OAUTH_TOKEN or a cloud provider never see it.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does 'Login reached its time limit · Please run /login' mean?
&lt;/h3&gt;

&lt;p&gt;It is new in Claude Code 2.1.318. Your claude.ai login has a fixed end date, and this message means it reached that date and cannot be renewed. Renewing the login earlier does not move the date. Run claude auth login, or /login inside a session, to start a new login. For unattended jobs, the 2.1.318 message itself suggests claude setup-token with CLAUDE_CODE_OAUTH_TOKEN.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I check when my Claude Code login expires?
&lt;/h3&gt;

&lt;p&gt;On 2.1.318 or later, run claude auth status: the JSON has a loginExpiresAt field with the date your stored claude.ai sign-in ends, and claude -p JSON results carry credential_expires_at. Inside a session, /status shows a Login row reading 'Expired — log in again' once a login can no longer be renewed. Interactive sessions also warn at startup when the login is within three days of expiring.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Claude Code keep logging me out?
&lt;/h3&gt;

&lt;p&gt;Usually one of these: your system clock is wrong (token checks depend on it), an older Claude Code build such as an IDE extension's bundled CLI runs on the same machine (fixed in 2.1.277), a short command like claude auth status exited in the middle of a token refresh (fixed in 2.1.301 and 2.1.317), another terminal signed in again to the same account (fixed in 2.1.318), or on macOS the login keychain was locked. Update with claude update, check your clock, and run /login once.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I log out of Claude Code?
&lt;/h3&gt;

&lt;p&gt;Type /logout at the Claude Code prompt, or run claude auth logout in a shell. Logging out removes all stored credentials, including saved MCP server logins and plugin secrets, and resets first-launch setup, so the next claude run walks you through login again.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I keep Claude Code logged in for CI or scripts?
&lt;/h3&gt;

&lt;p&gt;Run claude setup-token on a machine where browser sign-in works. It prints a one-year OAuth token without saving it; set it as CLAUDE_CODE_OAUTH_TOKEN where the job runs. It needs a Pro, Max, Ultra, Team or Enterprise plan, can only make model requests, and is ignored by --bare, which needs ANTHROPIC_API_KEY or an apiKeyHelper instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Claude Code say not logged in when ANTHROPIC_API_KEY is set?
&lt;/h3&gt;

&lt;p&gt;The variable has to be exported in the shell that starts claude, and in interactive mode Claude Code asks once whether to use the key; if you declined, it stays unused until you change the 'Use custom API key' toggle in /config. Background sessions and cloud workers need the key in their own environment, not just your interactive shell. Run /status to see which credential is active.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/authentication" rel="noopener noreferrer"&gt;Authentication (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;Error reference: Not logged in, Login expired, Could not refresh your login (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/troubleshoot-install" rel="noopener noreferrer"&gt;Troubleshoot installation and login: Not logged in or token expired (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/cli-reference" rel="noopener noreferrer"&gt;CLI reference: claude auth and claude setup-token (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (2.1.206 to 2.1.318)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@anthropic-ai/claude-code-linux-x64" rel="noopener noreferrer"&gt;@anthropic-ai/claude-code-linux-x64 2.1.318 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-not-logged-in-login-expired" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>claudecode</category>
    </item>
    <item>
      <title>Claude Code Now Starts in Auto Mode: I Read the 2.1.316 Build to See What Changed</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Thu, 05 Nov 2026 04:22:06 +0000</pubDate>
      <link>https://dev.to/its-tahir/claude-code-now-starts-in-auto-mode-i-read-the-21316-build-to-see-what-changed-41a2</link>
      <guid>https://dev.to/its-tahir/claude-code-now-starts-in-auto-mode-i-read-the-21316-build-to-see-what-changed-41a2</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;If Claude Code recently opened with "Auto mode is now Claude Code's default permission mode.", that's not a glitch: since 2.1.283, new terminal and VS Code sessions start in auto mode. I went through Anthropic's docs and the strings in the 2.1.316 build to map what it does, how to turn it off, and what each "auto mode unavailable" message really means. Are you keeping it on, or switching back to Manual?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Code auto mode lets a safety classifier approve Claude's actions instead of asking you for each one, without skipping permission checks entirely, and since Claude Code 2.1.283 (2.1.284 for every account) it is the mode new terminal and VS Code sessions start in. That's why you saw "Auto mode is now Claude Code's default permission mode." To turn it off, press &lt;code&gt;Shift+Tab&lt;/code&gt; once for this session, or set &lt;code&gt;"permissions": { "defaultMode": "default" }&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt; for every session.&lt;/strong&gt; To keep it, do nothing; to pin it, set &lt;code&gt;"defaultMode": "auto"&lt;/code&gt; in that same user file, because a project's &lt;code&gt;.claude/settings.json&lt;/code&gt; ignores &lt;code&gt;auto&lt;/code&gt;.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You want to&lt;/th&gt;
&lt;th&gt;Do this&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Leave auto mode in this session&lt;/td&gt;
&lt;td&gt;Press &lt;code&gt;Shift+Tab&lt;/code&gt; once (it switches to Manual)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Never start in auto mode on this machine&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;"permissions": { "defaultMode": "default" }&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Start one session without it&lt;/td&gt;
&lt;td&gt;&lt;code&gt;claude --permission-mode default&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Always start in auto mode&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;"permissions": { "defaultMode": "auto" }&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;, not the project file&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Stop VS Code conversations starting in it&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;claudeCode.initialPermissionMode&lt;/code&gt; in VS Code user settings&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Remove it for a whole organization&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;"permissions": { "disableAutoMode": "disable" }&lt;/code&gt; in managed settings&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last reviewed 2 November 2026, against Claude Code 2.1.316. The notices and "unavailable" messages below are quoted from the 2.1.316 Windows build, which I downloaded from npm into a throwaway folder and searched without installing it; the rest comes from Anthropic's permission-mode docs and changelog, linked at each point.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fxpk58aarf7dig2xf8y9u.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fxpk58aarf7dig2xf8y9u.png" alt="Claude Code permission modes compared. Manual (default, ⏸ manual mode on): only reads run without asking. Accept edits (⏵⏵ accept edits on): reads, file edits and mkdir, touch, rm, mv, cp, sed in the project. Plan (⏸ plan mode on): reads, plus classifier-approved commands while planning; no edits until you approve the plan. Auto (⏵⏵ auto mode on): everything, but a classifier reviews shell commands and network calls first and blocks risky ones; the starting mode since 2.1.283 (2.1.284 for every account). Don't ask (⏵⏵ don't ask on): only pre-approved tools; anything else is denied. Bypass permissions (--dangerously-skip-permissions): everything with no review; containers and VMs only. Shift+Tab from auto goes to Manual, then accept edits, then plan." width="800" height="667"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Six permission modes, from most prompts to none. Only auto mode puts a model between Claude and your shell.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What is auto mode in Claude Code?
&lt;/h2&gt;

&lt;p&gt;Auto mode is a &lt;a href="https://code.claude.com/docs/en/permission-modes" rel="noopener noreferrer"&gt;permission mode&lt;/a&gt; in which a second model, the classifier, reviews Claude's actions in place of you. The first-run text in the 2.1.316 build puts it plainly: "Auto mode lets Claude handle permission prompts automatically. Claude checks each tool call for risky actions and prompt injection before executing, runs the ones it assesses as lower-risk, and blocks the rest."&lt;/p&gt;

&lt;p&gt;In practice each action goes through a fixed order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Your rules first.&lt;/strong&gt; Anything your &lt;code&gt;allow&lt;/code&gt;, &lt;code&gt;ask&lt;/code&gt; or &lt;code&gt;deny&lt;/code&gt; rules match resolves straight away, with a few exceptions such as dangerous &lt;code&gt;rm&lt;/code&gt; paths.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Reads and edits in your project run.&lt;/strong&gt; Read-only actions and file edits inside your working directory don't go to the classifier.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Everything else goes to the classifier.&lt;/strong&gt; Shell commands, network requests, MCP tools and subagents are reviewed before they run.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A block comes back as a reason.&lt;/strong&gt; Claude receives the rule that blocked it, tries a safer approach, and the call is listed in &lt;code&gt;/permissions&lt;/code&gt; under &lt;strong&gt;Recently denied&lt;/strong&gt;, where &lt;code&gt;r&lt;/code&gt; retries it with your manual approval.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The status bar shows &lt;code&gt;⏵⏵ auto mode on&lt;/code&gt; while it's active. Auto mode also nudges Claude to keep working instead of stopping for clarifying questions, which is the most visible change from Manual.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why did Claude Code start in auto mode?
&lt;/h2&gt;

&lt;p&gt;Because auto mode is now the built-in starting mode. From Claude Code &lt;strong&gt;2.1.283&lt;/strong&gt;, the docs say interactive terminal and VS Code sessions start in auto mode on every plan and provider when nothing else picks a mode. The changelog rolled it out in two steps: 2.1.283 for third-party providers and telemetry-off sessions, then 2.1.284 for everyone. Before that, auto was the starting mode only on Pro, Max, Ultra and Team plans in sessions that fetched feature flags, per the &lt;a href="https://code.claude.com/docs/en/permission-modes#which-mode-a-session-starts-in" rel="noopener noreferrer"&gt;permission modes docs&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;The first session that starts this way shows a one-time notice. In the terminal it appears once at the top of the session:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Auto mode is now Claude Code's default permission mode.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In the VS Code extension it's a card on the new-conversation screen that stays until you dismiss it. If you had already set another &lt;code&gt;defaultMode&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;, nothing changes: your sessions keep starting in that mode, and on Pro, Max, Ultra and Team plans Claude Code asks you once whether to switch: "Make auto mode your default permission mode?"&lt;/p&gt;

&lt;p&gt;Claude Code picks the starting mode from the first of these that applies:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;A &lt;code&gt;--permission-mode&lt;/code&gt; flag, or &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;permissions.defaultMode&lt;/code&gt; in a settings file&lt;/li&gt;
&lt;li&gt;The built-in default, which is now &lt;code&gt;auto&lt;/code&gt; for interactive sessions&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Two exceptions keep the old behaviour. &lt;code&gt;claude -p&lt;/code&gt; and Agent SDK runs start in Manual mode (from 2.1.302), so scripts don't silently get a classifier. And if any settings file sets &lt;code&gt;disableAutoMode&lt;/code&gt; to &lt;code&gt;"disable"&lt;/code&gt;, or the session can't use auto mode, it starts in Manual.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I turn off auto mode in Claude Code?
&lt;/h2&gt;

&lt;p&gt;Press &lt;code&gt;Shift+Tab&lt;/code&gt; once to leave auto mode for the current session. To stop every session starting in it, set &lt;code&gt;"permissions": { "defaultMode": "default" }&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;. For one launch, run &lt;code&gt;claude --permission-mode default&lt;/code&gt;. Admins can remove it for everyone with &lt;code&gt;disableAutoMode&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  For this session: press Shift+Tab
&lt;/h3&gt;

&lt;p&gt;From auto mode, the first press of &lt;code&gt;Shift+Tab&lt;/code&gt; switches to Manual, shown as a gray &lt;code&gt;⏸ manual mode on&lt;/code&gt;. Further presses cycle Manual, accept edits and plan mode, then back to auto. In VS Code, click the mode indicator under the prompt box; in the desktop app, use the mode selector.&lt;/p&gt;

&lt;h3&gt;
  
  
  For every session on your machine: set defaultMode
&lt;/h3&gt;

&lt;p&gt;Add this to &lt;code&gt;~/.claude/settings.json&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"permissions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"defaultMode"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"default"&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;default&lt;/code&gt; is the config name for Manual mode, and Claude Code accepts &lt;code&gt;"manual"&lt;/code&gt; as an alias. The next session starts with &lt;code&gt;⏸ manual mode on&lt;/code&gt;. If you'd rather start in accept edits or plan mode, use &lt;code&gt;"acceptEdits"&lt;/code&gt; or &lt;code&gt;"plan"&lt;/code&gt; instead. A project's &lt;code&gt;.claude/settings.json&lt;/code&gt; can set &lt;code&gt;default&lt;/code&gt;, &lt;code&gt;acceptEdits&lt;/code&gt;, &lt;code&gt;plan&lt;/code&gt; or &lt;code&gt;dontAsk&lt;/code&gt; for that project only, and it outranks your user file: a project that sets &lt;code&gt;default&lt;/code&gt; overrides an &lt;code&gt;auto&lt;/code&gt; in your user file, but a project can't set &lt;code&gt;auto&lt;/code&gt; itself.&lt;/p&gt;

&lt;h3&gt;
  
  
  For one launch: use the flag
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--permission-mode&lt;/span&gt; default
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  In the VS Code extension
&lt;/h3&gt;

&lt;p&gt;The extension has its own setting. Set &lt;code&gt;claudeCode.initialPermissionMode&lt;/code&gt; in your VS Code &lt;strong&gt;user&lt;/strong&gt; settings to &lt;code&gt;default&lt;/code&gt;, &lt;code&gt;acceptEdits&lt;/code&gt;, &lt;code&gt;plan&lt;/code&gt; or &lt;code&gt;bypassPermissions&lt;/code&gt;. It never reads a project's &lt;code&gt;.claude/settings.json&lt;/code&gt; for the starting mode, and it remembers the mode you last picked from the indicator, so picking Manual once also sticks.&lt;/p&gt;

&lt;h3&gt;
  
  
  For a whole organization
&lt;/h3&gt;

&lt;p&gt;Set &lt;code&gt;"permissions": { "disableAutoMode": "disable" }&lt;/code&gt; in &lt;a href="https://code.claude.com/docs/en/managed-settings" rel="noopener noreferrer"&gt;managed settings&lt;/a&gt;. That removes auto from the &lt;code&gt;Shift+Tab&lt;/code&gt; cycle, makes &lt;code&gt;--permission-mode auto&lt;/code&gt; start in Manual, and switches a running auto session out with the message &lt;code&gt;auto mode disabled by settings&lt;/code&gt;. Setting &lt;code&gt;defaultMode&lt;/code&gt; in managed settings instead changes where sessions start while still letting people choose auto.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I turn auto mode on, or make it my default?
&lt;/h2&gt;

&lt;p&gt;On 2.1.283 or later (2.1.284 for every account) auto is already your starting mode, unless a &lt;code&gt;--permission-mode&lt;/code&gt; flag or a &lt;code&gt;permissions.defaultMode&lt;/code&gt; setting picks another. Otherwise:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Right now:&lt;/strong&gt; press &lt;code&gt;Shift+Tab&lt;/code&gt; until the status bar shows &lt;code&gt;⏵⏵ auto mode on&lt;/code&gt;. Auto only appears in the cycle when it's available to your session.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;From a permission prompt:&lt;/strong&gt; in Manual and accept edits, a Bash permission prompt offers &lt;strong&gt;Yes, and switch to auto mode&lt;/strong&gt; (2.1.247 or later).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;After a plan:&lt;/strong&gt; approving a plan offers &lt;strong&gt;Yes, and use auto mode&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;For one launch:&lt;/strong&gt; &lt;code&gt;claude --permission-mode auto&lt;/code&gt;. This is also how to get auto mode in &lt;code&gt;claude -p&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;As your default:&lt;/strong&gt; &lt;code&gt;"defaultMode": "auto"&lt;/code&gt; under &lt;code&gt;permissions&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That last one has a trap. &lt;code&gt;"auto"&lt;/code&gt; has &lt;strong&gt;no effect&lt;/strong&gt; in a project's &lt;code&gt;.claude/settings.json&lt;/code&gt; or &lt;code&gt;.claude/settings.local.json&lt;/code&gt;; Claude Code ignores it there and falls back to the built-in default. If you set &lt;code&gt;auto&lt;/code&gt; and your sessions still start in Manual with no error, that's almost always why. Move it to the user file. In VS Code, &lt;code&gt;claudeCode.initialPermissionMode&lt;/code&gt; doesn't accept &lt;code&gt;auto&lt;/code&gt; either: leave it unset and pick &lt;strong&gt;Auto&lt;/strong&gt; from the mode indicator once.&lt;/p&gt;

&lt;h2&gt;
  
  
  How is auto mode different from accept edits, plan mode and bypass permissions?
&lt;/h2&gt;

&lt;p&gt;Auto mode is the only mode that runs shell commands without asking while a classifier model still reviews them. Accept edits only skips edit and basic file-command prompts, plan mode blocks edits until you approve a plan, and bypass permissions skips review entirely.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Mode&lt;/th&gt;
&lt;th&gt;Status bar&lt;/th&gt;
&lt;th&gt;Runs without asking&lt;/th&gt;
&lt;th&gt;Best for&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Manual (&lt;code&gt;default&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏸ manual mode on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Reads only&lt;/td&gt;
&lt;td&gt;Sensitive work, reviewing every step&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Accept edits (&lt;code&gt;acceptEdits&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏵⏵ accept edits on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Reads, file edits, and &lt;code&gt;mkdir&lt;/code&gt;, &lt;code&gt;touch&lt;/code&gt;, &lt;code&gt;rm&lt;/code&gt;, &lt;code&gt;mv&lt;/code&gt;, &lt;code&gt;cp&lt;/code&gt;, &lt;code&gt;sed&lt;/code&gt; inside the project&lt;/td&gt;
&lt;td&gt;Iterating on code you review with &lt;code&gt;git diff&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Plan (&lt;code&gt;plan&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏸ plan mode on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Reads, plus classifier-approved commands when auto mode is available; no edits until you approve the plan&lt;/td&gt;
&lt;td&gt;Exploring before changing anything&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Auto (&lt;code&gt;auto&lt;/code&gt;)&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏵⏵ auto mode on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Everything, after the classifier reviews risky actions&lt;/td&gt;
&lt;td&gt;Long tasks without prompt fatigue&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Don't ask (&lt;code&gt;dontAsk&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏵⏵ don't ask on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Reads plus pre-approved tools; anything else is denied&lt;/td&gt;
&lt;td&gt;CI and scripts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Bypass (&lt;code&gt;bypassPermissions&lt;/code&gt;)&lt;/td&gt;
&lt;td&gt;&lt;code&gt;⏵⏵ bypass permissions on&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Everything, no review&lt;/td&gt;
&lt;td&gt;Isolated containers and VMs only&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Auto mode vs accept edits.&lt;/strong&gt; Accept edits saves you the edit prompts but still stops for every other shell command, so a test run or a &lt;code&gt;git&lt;/code&gt; command asks. Auto mode stops asking for those too and puts the classifier in your place. If what bothers you is only the edit prompts, accept edits is the smaller change.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Auto mode vs plan mode.&lt;/strong&gt; They work together rather than compete. Plan mode keeps Claude from editing until you approve a plan; with auto mode available, its exploration commands go through the classifier instead of prompting. Approving the plan with &lt;strong&gt;Yes, and use auto mode&lt;/strong&gt; carries on in auto.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Auto mode vs bypass permissions (&lt;code&gt;--dangerously-skip-permissions&lt;/code&gt;).&lt;/strong&gt; Both remove the prompts. Bypass removes the checks too: every action runs immediately, which is why Anthropic says to use it only in containers and VMs, and why on Linux and macOS it refuses to start as root. Auto mode keeps a reviewer. Deny rules apply in both. If you were reaching for &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt; to stop the interruptions, auto mode is usually the better trade; the &lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;sandbox and Docker guide&lt;/a&gt; covers when you really do need bypass.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does auto mode block, and what does it allow?
&lt;/h2&gt;

&lt;p&gt;Out of the box the classifier trusts your working directory and the git remotes configured when the session started, and treats everything else as external. Among many others, it &lt;strong&gt;blocks&lt;/strong&gt; by default:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Downloading and running code, like &lt;code&gt;curl | bash&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Production deploys and migrations, and &lt;code&gt;terraform destroy&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;git push --force&lt;/code&gt;, and &lt;code&gt;git reset --hard&lt;/code&gt;, &lt;code&gt;git clean -fd&lt;/code&gt; or &lt;code&gt;git checkout -- .&lt;/code&gt; that would discard uncommitted work&lt;/li&gt;
&lt;li&gt;Sending secrets or sensitive data to outside endpoints, or printing a live token into the transcript&lt;/li&gt;
&lt;li&gt;Deleting files that existed before the session, and mass deletes in cloud storage&lt;/li&gt;
&lt;li&gt;Starting another agent with &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt;
&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;It &lt;strong&gt;allows&lt;/strong&gt; local file work in your project, installing dependencies your lock files declare, read-only HTTP requests, and pushing to any branch of the repository you're in, apart from deploy branches like &lt;code&gt;production&lt;/code&gt; or &lt;code&gt;gh-pages&lt;/code&gt;. &lt;code&gt;claude auto-mode defaults&lt;/code&gt; prints the full rule lists as JSON.&lt;/p&gt;

&lt;p&gt;Three behaviors catch people out:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Broad allow rules are dropped while you're in auto mode.&lt;/strong&gt; &lt;code&gt;Bash(*)&lt;/code&gt;, wildcard interpreters like &lt;code&gt;Bash(python*)&lt;/code&gt;, package-manager run commands and &lt;code&gt;Agent&lt;/code&gt; rules are set aside on entering auto mode and restored when you leave. Narrow rules like &lt;code&gt;Bash(npm test)&lt;/code&gt; stay.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;What you say in the conversation counts.&lt;/strong&gt; "Don't push" becomes a block until you lift it. But those boundaries aren't stored as rules, and &lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;compaction&lt;/a&gt; can drop the message that set them. For a hard limit, write a deny rule.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Repeated blocks pause it.&lt;/strong&gt; Three blocks in a row or 20 in a session and auto mode pauses and Claude Code goes back to prompting; approving the prompted action resumes it. The thresholds aren't configurable.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why is auto mode unavailable, missing or not working?
&lt;/h2&gt;

&lt;p&gt;When auto mode can't run, it disappears from the &lt;code&gt;Shift+Tab&lt;/code&gt; cycle and sessions that would start in it start in Manual instead. The status line names the reason. These are the exact messages in the 2.1.316 build:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Message&lt;/th&gt;
&lt;th&gt;What it means&lt;/th&gt;
&lt;th&gt;What to do&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;auto mode disabled by settings&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;A settings file sets &lt;code&gt;disableAutoMode&lt;/code&gt; to &lt;code&gt;"disable"&lt;/code&gt;, usually your organization's managed settings&lt;/td&gt;
&lt;td&gt;Ask your admin; you can't override managed settings locally&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;auto mode is unavailable for your plan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Despite the wording, this is the circuit-breaker case: Anthropic or the server has turned auto mode off for this session. Auto mode itself is on all plans&lt;/td&gt;
&lt;td&gt;Start a new session later; it stays off until the session ends&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;auto mode unavailable for this model&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Your model doesn't support auto mode&lt;/td&gt;
&lt;td&gt;Switch with &lt;code&gt;/model&lt;/code&gt;. On the Anthropic API that means Opus 4.6+, Sonnet 4.6+, Haiku 5.5 or a Fable model; on Bedrock, Agent Platform and Foundry, Sonnet 5+, Opus 4.7+, Haiku 5.5 or Fable, per the &lt;a href="https://code.claude.com/docs/en/permission-modes#eliminate-permission-prompts-with-auto-mode" rel="noopener noreferrer"&gt;permission modes docs&lt;/a&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;auto mode unavailable while fast mode is on · run /fast off&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Fast mode and auto mode don't run together&lt;/td&gt;
&lt;td&gt;Run &lt;code&gt;/fast off&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;auto mode is unavailable right now&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;No specific reason was recorded&lt;/td&gt;
&lt;td&gt;Start a new session; check the items above&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two other cases look like "auto mode isn't working" but aren't on that list:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It's set but sessions start in Manual, with no message.&lt;/strong&gt; &lt;code&gt;"defaultMode": "auto"&lt;/code&gt; is in a project settings file, where it's ignored. Move it to &lt;code&gt;~/.claude/settings.json&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Auto mode is on but blocks everything, even &lt;code&gt;pwd&lt;/code&gt;.&lt;/strong&gt; That's the safety check failing to answer, not the mode being off. Messages like &lt;code&gt;Auto mode is unavailable — the server returned no safety verdict&lt;/code&gt; and "cannot determine the safety of" belong here, and &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode-classifier-no-verdict" rel="noopener noreferrer"&gt;Claude Code auto mode "gave no verdict"&lt;/a&gt; walks through the fixes. My &lt;a href="https://tools.its-tahir.com/errors/auto-mode-no-safety-verdict" rel="noopener noreferrer"&gt;error page for the same message&lt;/a&gt; has the short version.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If auto mode disappeared after an update, check whether you're on a model it supports, and run &lt;code&gt;/status&lt;/code&gt;: the &lt;code&gt;Auto mode server&lt;/code&gt; row shows whether the server is reviewing your session's actions.&lt;/p&gt;

&lt;h2&gt;
  
  
  Does auto mode use more tokens or cost more?
&lt;/h2&gt;

&lt;p&gt;It depends on your account. Each check Claude Code sends to the classifier includes part of the transcript plus the pending action, and the default classifier model is Claude Sonnet 5, whatever model you chose with &lt;code&gt;/model&lt;/code&gt;.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Pro, Max, Ultra and Team plans:&lt;/strong&gt; no separate classifier charge is listed for these plans, and the billing notice about classifier requests never appears on them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Enterprise, the Claude API, Claude Platform on AWS, Bedrock, Agent Platform and Foundry:&lt;/strong&gt; Claude Code's own classifier calls count toward your token usage.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Server-side review:&lt;/strong&gt; where the server checks actions as part of your normal model request, there are no separate classifier calls at all. &lt;code&gt;/status&lt;/code&gt; shows &lt;code&gt;Auto mode server: Enabled&lt;/code&gt; when that's happening.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Reads and edits inside your project skip the classifier, so the overhead comes mostly from shell commands and network calls. If you saw "We're changing auto mode to no longer charge for classifier requests" followed by "this session isn't eligible", that's a gateway issue covered in &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode-classifier-billing" rel="noopener noreferrer"&gt;auto mode classifier billing&lt;/a&gt;. For a model-by-model cost estimate, the &lt;a href="https://tools.its-tahir.com/llm-cost-calculator" rel="noopener noreferrer"&gt;LLM cost calculator&lt;/a&gt; does the arithmetic.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I stop auto mode blocking safe commands?
&lt;/h2&gt;

&lt;p&gt;Run &lt;code&gt;/auto-mode-setup&lt;/code&gt;, or list what you trust in &lt;code&gt;autoMode.environment&lt;/code&gt;. Most false blocks come from the classifier not knowing what you trust: your company's buckets, internal registries, deploy hosts. Two ways to tell it:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;/auto-mode-setup&lt;/code&gt;&lt;/strong&gt; reads your project and recent sessions and drafts environment entries for you to review before saving. From 2.1.304 it also works on Bedrock, Vertex, Foundry, the Claude apps gateway and telemetry-off sessions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;autoMode&lt;/code&gt; settings:&lt;/strong&gt; &lt;code&gt;autoMode.environment&lt;/code&gt; lists trusted infrastructure, and &lt;code&gt;autoMode.allow&lt;/code&gt; adds exceptions to the block rules. Include &lt;code&gt;"$defaults"&lt;/code&gt; in an &lt;code&gt;allow&lt;/code&gt; list you write, or you replace the built-in exceptions instead of adding to them. Anthropic's &lt;a href="https://code.claude.com/docs/en/auto-mode-config" rel="noopener noreferrer"&gt;auto mode configuration guide&lt;/a&gt; has the full format.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To keep a human checkpoint inside auto mode, for example before every &lt;code&gt;git push&lt;/code&gt;, add a &lt;code&gt;permissions.ask&lt;/code&gt; rule such as &lt;code&gt;Bash(git push *)&lt;/code&gt;. Ask rules still prompt in auto mode. My &lt;a href="https://tools.its-tahir.com/claude-code-settings" rel="noopener noreferrer"&gt;Claude Code settings builder&lt;/a&gt; writes the &lt;code&gt;permissions&lt;/code&gt; block, including &lt;code&gt;defaultMode&lt;/code&gt; and ask rules, without hand-editing JSON.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is Claude Code auto mode safe?
&lt;/h2&gt;

&lt;p&gt;Safer than skipping permissions, and not a guarantee. Anthropic's own docs put it in a warning: auto mode "reduces permission prompts but does not guarantee safety." The classifier never sees tool results in Claude Code's own classifier requests, so a hostile web page can't talk to it directly, and a separate server-side probe flags suspicious tool results before Claude reads them. But it makes judgment calls, and boundaries you state in chat can be compacted away.&lt;/p&gt;

&lt;p&gt;The practical setup: let auto mode handle the routine prompts, keep &lt;code&gt;deny&lt;/code&gt; rules for anything that must never happen, add &lt;code&gt;ask&lt;/code&gt; rules for steps you want to see, and commit before long runs. For unattended work, put a &lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;sandbox or container&lt;/a&gt; around it. And if it's already too late, &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;Claude Code deleted my files&lt;/a&gt; covers what you can get back.&lt;/p&gt;

&lt;h2&gt;
  
  
  What changed in auto mode recently?
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Change&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.316&lt;/td&gt;
&lt;td&gt;An &lt;code&gt;autoMode.allow&lt;/code&gt; list without &lt;code&gt;"$defaults"&lt;/code&gt; no longer removes the built-in rule on scheduled-task prompts&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.314&lt;/td&gt;
&lt;td&gt;Blocked-call messages name the command, say Claude may retry, and point to &lt;code&gt;/permissions&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.304&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/auto-mode-setup&lt;/code&gt; added for Bedrock, Vertex, Foundry, Claude apps gateway and telemetry-off sessions&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.302&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;claude -p&lt;/code&gt; and Agent SDK runs with no mode set start in Manual; &lt;code&gt;CLAUDE_CODE_AUTO_MODE_MODEL&lt;/code&gt; chooses the client-side classifier model&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.288&lt;/td&gt;
&lt;td&gt;A conversation too long for the client-side classifier is compacted instead of failing every check&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.285&lt;/td&gt;
&lt;td&gt;The one-time "make auto mode your default" offer also shows on third-party providers and with telemetry off&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.284&lt;/td&gt;
&lt;td&gt;Interactive terminal and VS Code sessions start in auto mode on every plan and provider&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.283&lt;/td&gt;
&lt;td&gt;Interactive sessions on third-party providers or with telemetry off start in auto mode&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.278&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/status&lt;/code&gt; gains an &lt;code&gt;Auto mode server&lt;/code&gt; row&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.247&lt;/td&gt;
&lt;td&gt;Bash permission prompts offer &lt;strong&gt;Yes, and switch to auto mode&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Auto mode lets a classifier model approve Claude's actions instead of you. Reads and edits in your project run directly; shell commands, network calls and MCP tools are reviewed first.&lt;/li&gt;
&lt;li&gt;Since Claude Code 2.1.283 (2.1.284 for every account) it is the starting mode for interactive terminal and VS Code sessions, which is why you saw 'Auto mode is now Claude Code's default permission mode.'&lt;/li&gt;
&lt;li&gt;To turn it off: Shift+Tab once for this session, or "permissions": { "defaultMode": "default" } in ~/.claude/settings.json for every session. VS Code uses claudeCode.initialPermissionMode.&lt;/li&gt;
&lt;li&gt;"defaultMode": "auto" only works in ~/.claude/settings.json or managed settings; in a project's .claude/settings.json it is ignored.&lt;/li&gt;
&lt;li&gt;'auto mode is unavailable for your plan' is the circuit-breaker message, not a plan limit: auto mode is on all plans. Start a new session later.&lt;/li&gt;
&lt;li&gt;Auto mode is not a sandbox. Keep deny rules for hard limits and run unattended work in a container.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;Auto mode is one corner of a bigger picture: &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;the full list of Claude Code errors and fixes&lt;/a&gt; covers the rest, and the &lt;a href="https://tools.its-tahir.com/guides/claude-code-plan-mode" rel="noopener noreferrer"&gt;plan mode guide&lt;/a&gt; pairs well with this one. Setting up coding agents so teams can run them with fewer prompts and no surprises is part of the work I do: &lt;a href="https://www.its-tahir.com/work" rel="noopener noreferrer"&gt;see recent projects&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  What is auto mode in Claude Code?
&lt;/h3&gt;

&lt;p&gt;Auto mode is a permission mode in which a second model, the classifier, reviews Claude's actions instead of asking you. Reads and file edits inside your project run straight away, and shell commands, network calls and other actions go to the classifier, which blocks anything that goes beyond your request, targets infrastructure it doesn't recognize, or looks driven by content Claude read. The status bar shows ⏵⏵ auto mode on.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why did Claude Code start in auto mode?
&lt;/h3&gt;

&lt;p&gt;Because auto mode became the built-in starting permission mode. From Claude Code 2.1.283 (2.1.284 for every account, per the changelog), interactive terminal and VS Code sessions start in auto mode on every plan and provider when nothing else sets a permission mode, and the first such session shows 'Auto mode is now Claude Code's default permission mode.' A --permission-mode flag or permissions.defaultMode in your settings still overrides it.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I turn off auto mode in Claude Code?
&lt;/h3&gt;

&lt;p&gt;For the current session, press Shift+Tab once: from auto mode the first press switches to Manual. For every session on your machine, add "permissions": { "defaultMode": "default" } to ~/.claude/settings.json (manual is accepted as an alias). For one launch, run claude --permission-mode default. In the VS Code extension, set claudeCode.initialPermissionMode. To remove auto mode for a whole organization, set permissions.disableAutoMode to "disable" in managed settings.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I make auto mode my default in Claude Code?
&lt;/h3&gt;

&lt;p&gt;On 2.1.283 or later (2.1.284 for every account) it already is, unless a settings file or flag picks another mode. To pin it, set "defaultMode": "auto" under permissions in ~/.claude/settings.json. The value has no effect in a project's .claude/settings.json or .claude/settings.local.json, which is the usual reason a session still starts in Manual. For a single run, pass claude --permission-mode auto.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the difference between auto mode and accept edits?
&lt;/h3&gt;

&lt;p&gt;Accept edits only auto-approves file edits and the filesystem commands mkdir, touch, rm, mv, cp and sed inside your project; every other shell command still asks you. Auto mode runs everything without a prompt, but a classifier model reviews shell commands, network calls and other risky actions first and blocks the ones it judges unsafe.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the difference between auto mode and --dangerously-skip-permissions?
&lt;/h3&gt;

&lt;p&gt;--dangerously-skip-permissions starts bypassPermissions mode, which runs every action with no review at all and is meant for containers and VMs. Auto mode also runs without prompts, but each risky action is checked by a classifier first, and blocked actions show up in /permissions under Recently denied. Deny rules apply in both.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does Claude Code say auto mode is unavailable for your plan?
&lt;/h3&gt;

&lt;p&gt;Despite the wording, auto mode is available on all plans. In the 2.1.316 build, 'auto mode is unavailable for your plan' is the message for the circuit-breaker case: Anthropic or the server has turned auto mode off for the session. That lasts until the session ends, so start a new session later. Other messages name other causes: 'auto mode disabled by settings', 'auto mode unavailable for this model' and 'auto mode unavailable while fast mode is on · run /fast off'.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does auto mode use more tokens?
&lt;/h3&gt;

&lt;p&gt;Only on some accounts. On Enterprise, the Claude API, Claude Platform on AWS, Bedrock, Agent Platform and Foundry, each classifier check Claude Code sends counts toward token usage, because it sends part of the transcript plus the pending action. On Pro, Max, Ultra and Team the docs list no classifier charges. Where the server reviews actions as part of the normal model request, there are no separate classifier calls. Reads and edits in your project skip the classifier, so the extra cost comes mostly from shell commands.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Claude Code auto mode safe?
&lt;/h3&gt;

&lt;p&gt;Safer than skipping permissions, not a guarantee. Anthropic's docs say auto mode "reduces permission prompts but does not guarantee safety." It blocks things like curl | bash, force pushes, production deploys and git reset --hard by default, but it reads boundaries from the conversation, which compaction can drop. For a hard limit, add a deny rule; for unattended runs, add a sandbox or container.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/permission-modes" rel="noopener noreferrer"&gt;Choose a permission mode (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/auto-mode-config" rel="noopener noreferrer"&gt;Configure auto mode (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/auto-mode-classifier-billing" rel="noopener noreferrer"&gt;Auto mode classifier billing (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/permissions" rel="noopener noreferrer"&gt;Configure permissions (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (2.1.247 to 2.1.316)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.npmjs.com/package/@anthropic-ai/claude-code-win32-x64" rel="noopener noreferrer"&gt;@anthropic-ai/claude-code-win32-x64 2.1.316 (npm)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>programming</category>
      <category>productivity</category>
      <category>claudecode</category>
    </item>
    <item>
      <title>I tried running Claude Code's sandbox inside Docker. bubblewrap couldn't even start</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Sat, 31 Oct 2026 03:31:57 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-tried-running-claude-codes-sandbox-inside-docker-bubblewrap-couldnt-even-start-4faj</link>
      <guid>https://dev.to/its-tahir/i-tried-running-claude-codes-sandbox-inside-docker-bubblewrap-couldnt-even-start-4faj</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Running Claude Code in a container and turning on its built-in sandbox inside it sounds like belt and braces. So I tested it on Docker Desktop: in a default container, bubblewrap failed with 'No permissions to create new namespace', and Anthropic's docs say Claude Code then runs commands unsandboxed unless you tell it not to. Below is what I tested, the Dockerfile that does work, and how the sandbox behaves on macOS, Linux, WSL2 and native Windows. How are you isolating Claude Code: a container, a VM, or just /sandbox?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Code has a built-in sandbox for shell commands: run &lt;code&gt;/sandbox&lt;/code&gt; in a session, or set &lt;code&gt;"sandbox": { "enabled": true }&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;. It works on macOS, Linux and WSL2, not on native Windows. It only covers shell commands, so for unattended runs with &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt;, put the whole Claude Code process in a Docker container, a VM or the sandbox runtime instead.&lt;/strong&gt; And if you combine the two, know this first: in my test with the sandbox runtime 0.0.81, bubblewrap, the tool Claude Code's sandbox uses on Linux, couldn't start inside a default Docker container at all.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;You want to&lt;/th&gt;
&lt;th&gt;Use&lt;/th&gt;
&lt;th&gt;Works on&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Fewer permission prompts on your own machine&lt;/td&gt;
&lt;td&gt;The built-in sandbox, &lt;code&gt;/sandbox&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;macOS, Linux, WSL2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Run with &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;A Docker or dev container, as a non-root user&lt;/td&gt;
&lt;td&gt;Anywhere Docker runs, including Windows&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Isolate MCP servers and hooks too, without Docker&lt;/td&gt;
&lt;td&gt;The sandbox runtime, &lt;code&gt;srt claude&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;macOS, Linux, WSL2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Work on a repository you don't trust&lt;/td&gt;
&lt;td&gt;A VM, or a cloud session&lt;/td&gt;
&lt;td&gt;Anywhere&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Use Claude Code on native Windows&lt;/td&gt;
&lt;td&gt;WSL2 for the sandbox, or Docker Desktop&lt;/td&gt;
&lt;td&gt;Windows&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last checked 30 October 2026, against Claude Code 2.1.314 and sandbox runtime 0.0.81. The Docker tests in this post ran on my own Windows 11 machine with Docker Desktop (WSL2 backend), and every test image, container and volume was removed afterwards.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F5vw06w525ei42z9tznxc.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F5vw06w525ei42z9tznxc.png" alt="Claude Code sandbox options compared. Built-in Bash sandbox (/sandbox): isolates shell commands and child processes, not file tools, MCP servers or hooks; no native Windows, use WSL2; not enough alone for --dangerously-skip-permissions. Sandbox runtime (srt claude): isolates the whole process; no native Windows; suitable, beta. Docker or dev container: isolates the whole process; works on Windows with Docker Desktop; suitable as non-root. VM or cloud session: isolates a full OS; suitable. Tested: bubblewrap inside a default Docker container fails with bwrap: No permissions to create new namespace; when the sandbox can't start, Claude Code runs commands unsandboxed by default unless sandbox.failIfUnavailable is true." width="800" height="733"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Pick by what you need isolated. Only the container, VM and sandbox runtime cover file tools, MCP servers and hooks as well as shell commands.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What the Claude Code sandbox isolates
&lt;/h2&gt;

&lt;p&gt;Claude Code's built-in sandbox uses bubblewrap on Linux and WSL2, and Apple's Seatbelt on macOS, to put an operating-system boundary around the shell commands Claude runs: Bash, PowerShell and Monitor commands, plus every process they start. Covering child processes is what makes it different from permission rules. A test runner, a build script or a &lt;code&gt;node&lt;/code&gt; script that Claude launches is inside the same boundary, so a delete hidden in a test can't reach your home folder.&lt;/p&gt;

&lt;p&gt;With the sandbox on, by default:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;&lt;/th&gt;
&lt;th&gt;Allowed&lt;/th&gt;
&lt;th&gt;Change it with&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Writes&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;The working directory, a per-user temp folder, and directories you added with &lt;code&gt;--add-dir&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sandbox.filesystem.allowWrite&lt;/code&gt;, &lt;code&gt;denyWrite&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Reads&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Most of the machine, including &lt;code&gt;~/.ssh&lt;/code&gt; and &lt;code&gt;~/.aws/credentials&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sandbox.filesystem.denyRead&lt;/code&gt;, &lt;code&gt;sandbox.credentials&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Network&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;No direct route out; a local proxy allows only approved domains, and the list starts empty&lt;/td&gt;
&lt;td&gt;&lt;code&gt;sandbox.network.allowedDomains&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;strong&gt;Environment&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Inherited, including secrets in it&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;sandbox.credentials&lt;/code&gt;, &lt;code&gt;CLAUDE_CODE_SUBPROCESS_ENV_SCRUB&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Some files in the project stay write-protected even inside it: the &lt;code&gt;.claude&lt;/code&gt; settings, skills, agents, commands and hooks folders, &lt;code&gt;.mcp.json&lt;/code&gt;, shell startup files, &lt;code&gt;.vscode&lt;/code&gt;, &lt;code&gt;.idea&lt;/code&gt;, and &lt;code&gt;hooks&lt;/code&gt; and &lt;code&gt;config&lt;/code&gt; inside &lt;code&gt;.git&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;What it &lt;strong&gt;doesn't&lt;/strong&gt; cover is just as important:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Claude's own file tools.&lt;/strong&gt; Read, Edit and Write run inside Claude Code, outside the sandbox, and follow permission rules instead. A &lt;code&gt;denyRead&lt;/code&gt; entry doesn't stop the Read tool.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MCP servers, hooks, plugin monitors and your status line command.&lt;/strong&gt; They run with your full access.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Commands you type at the &lt;code&gt;!&lt;/code&gt; prompt&lt;/strong&gt;, commands listed in &lt;code&gt;excludedCommands&lt;/code&gt;, and commands Claude retries outside the sandbox after a failure (&lt;code&gt;allowUnsandboxedCommands: false&lt;/code&gt; turns those retries off).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Files inside the project.&lt;/strong&gt; In my sandbox runtime test, an &lt;code&gt;rm -rf&lt;/code&gt; of a folder inside the project went through. The sandbox protects everything around your project, not the project itself.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  How to enable the sandbox in Claude Code
&lt;/h2&gt;

&lt;p&gt;Run &lt;code&gt;/sandbox&lt;/code&gt; in a Claude Code session and pick &lt;strong&gt;Auto-allow&lt;/strong&gt; or &lt;strong&gt;Regular permissions&lt;/strong&gt;; that writes the project's &lt;code&gt;.claude/settings.local.json&lt;/code&gt;. For every project, set &lt;code&gt;sandbox.enabled&lt;/code&gt; to &lt;code&gt;true&lt;/code&gt; in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;. Linux and WSL2 need &lt;code&gt;bubblewrap&lt;/code&gt; and &lt;code&gt;socat&lt;/code&gt; installed first; macOS uses Seatbelt, so there's nothing to install. Step by step:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Install the dependencies (Linux and WSL2 only).&lt;/strong&gt; macOS uses its built-in Seatbelt framework, so skip this step there.
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;   &lt;span class="nb"&gt;sudo &lt;/span&gt;apt-get &lt;span class="nb"&gt;install &lt;/span&gt;bubblewrap socat    &lt;span class="c"&gt;# Ubuntu, Debian&lt;/span&gt;
   &lt;span class="nb"&gt;sudo &lt;/span&gt;dnf &lt;span class="nb"&gt;install &lt;/span&gt;bubblewrap socat        &lt;span class="c"&gt;# Fedora&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;&lt;p&gt;&lt;strong&gt;Run &lt;code&gt;/sandbox&lt;/code&gt;&lt;/strong&gt; in a Claude Code session. If a package is missing, the panel shows only a &lt;strong&gt;Dependencies&lt;/strong&gt; tab that names it. Install it, restart Claude Code, and run &lt;code&gt;/sandbox&lt;/code&gt; again.&lt;/p&gt;&lt;/li&gt;
&lt;li&gt;
&lt;p&gt;&lt;strong&gt;Pick a mode&lt;/strong&gt; on the &lt;strong&gt;Mode&lt;/strong&gt; tab:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Auto-allow:&lt;/strong&gt; sandboxed commands run without a permission prompt. Deny rules, content-scoped ask rules such as &lt;code&gt;Bash(git push *)&lt;/code&gt;, and the check for dangerous &lt;code&gt;rm&lt;/code&gt; commands still apply.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Regular permissions:&lt;/strong&gt; the sandbox enforces the same limits, and you still approve each command.&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;That saves to the project's &lt;code&gt;.claude/settings.local.json&lt;/code&gt;. To turn the sandbox on for every project, put it in &lt;code&gt;~/.claude/settings.json&lt;/code&gt; instead. These are the settings I'd use:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sandbox"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"enabled"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"failIfUnavailable"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"allowUnsandboxedCommands"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"network"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="nl"&gt;"allowedDomains"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"registry.npmjs.org"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"github.com"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;failIfUnavailable: true&lt;/code&gt;&lt;/strong&gt; makes Claude Code exit at startup when the sandbox can't start. Without it, Claude Code quietly runs commands &lt;strong&gt;unsandboxed&lt;/strong&gt; when a dependency is missing or the platform isn't supported. That default is the one to change first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;allowUnsandboxedCommands: false&lt;/code&gt;&lt;/strong&gt; removes the escape hatch where Claude retries a failing command outside the sandbox. While retries are allowed, an allow rule that matches the command approves the unsandboxed retry with no prompt.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;allowedDomains&lt;/code&gt;&lt;/strong&gt; is the network allowlist. List what your package manager and Git remote need; the first time a command needs a new domain, Claude Code asks you.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To try it for one session without saving anything, start Claude Code with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--settings&lt;/span&gt; &lt;span class="s1"&gt;'{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To turn the sandbox off again, set &lt;code&gt;"enabled": false&lt;/code&gt; in the settings file that turned it on: &lt;code&gt;.claude/settings.local.json&lt;/code&gt; if you used &lt;code&gt;/sandbox&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Check that commands really run sandboxed
&lt;/h3&gt;

&lt;p&gt;Ask Claude (don't type it yourself at &lt;code&gt;!&lt;/code&gt;) to run:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;touch&lt;/span&gt; ~/sandbox-probe
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Inside the sandbox it fails with &lt;code&gt;Read-only file system&lt;/code&gt; on Linux and WSL2, the same error my sandboxed &lt;code&gt;rm&lt;/code&gt; got in the sandbox runtime Docker test further down, or &lt;code&gt;Operation not permitted&lt;/code&gt; on macOS. If the file gets created, delete it and run &lt;code&gt;/sandbox&lt;/code&gt; to see what's missing. If Claude asks to retry the command outside the sandbox, say no.&lt;/p&gt;

&lt;h2&gt;
  
  
  Claude Code sandbox on Windows
&lt;/h2&gt;

&lt;p&gt;The built-in sandbox doesn't run on native Windows. Anthropic's Claude Code docs put it plainly: "On native Windows, Claude Code runs commands unsandboxed." You have three ways to get one:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;WSL2.&lt;/strong&gt; Install a Linux distribution (&lt;code&gt;wsl --install -d Ubuntu&lt;/code&gt;), install Claude Code, &lt;code&gt;bubblewrap&lt;/code&gt; and &lt;code&gt;socat&lt;/code&gt; inside it, and use &lt;code&gt;/sandbox&lt;/code&gt; there. Check you're on WSL2 with &lt;code&gt;wsl -l -v&lt;/code&gt;; on WSL1, Claude Code reports &lt;code&gt;Sandboxing requires WSL2&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Docker Desktop.&lt;/strong&gt; Run Claude Code in a container, as shown in How to run Claude Code in Docker. This is the route I tested.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A VM or a cloud session&lt;/strong&gt;, if you need a full separate operating system.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;On Ubuntu 24.04 and later, including inside WSL2, AppArmor can stop bubblewrap from creating the namespaces it needs. Run &lt;code&gt;sysctl kernel.apparmor_restrict_unprivileged_userns&lt;/code&gt;: if it prints &lt;code&gt;1&lt;/code&gt;, the &lt;a href="https://code.claude.com/docs/en/sandboxing#set-up-linux-and-wsl2" rel="noopener noreferrer"&gt;sandboxing docs&lt;/a&gt; have a small AppArmor profile that lifts it for &lt;code&gt;bwrap&lt;/code&gt; only. Since 2.1.310, &lt;code&gt;/sandbox&lt;/code&gt; names this restriction itself when it's the cause.&lt;/p&gt;

&lt;p&gt;On native Windows without any of these, you still get the PowerShell tool's built-in guards: &lt;code&gt;Remove-Item&lt;/code&gt; on a drive root, a system folder or your home folder is refused in every mode. That stops the worst deletes, not a sandbox's worth of them. &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files#what-each-protection-actually-stops" rel="noopener noreferrer"&gt;What Claude Code's protections each stop&lt;/a&gt; has the full comparison.&lt;/p&gt;

&lt;h2&gt;
  
  
  How to run Claude Code in Docker
&lt;/h2&gt;

&lt;p&gt;To run Claude Code in Docker, build an image that installs it with npm and switches to a non-root user, then mount your project and keep &lt;code&gt;~/.claude&lt;/code&gt; in a named volume. The container puts all of Claude Code inside the boundary: shell commands, file tools, MCP servers and hooks. Anthropic recommends a container, a VM or the sandbox runtime for every &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt; session. Here's a minimal image I built and tested:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;FROM node:22-bookworm-slim
RUN apt-get update &amp;amp;&amp;amp; apt-get install -y --no-install-recommends git ca-certificates \
    &amp;amp;&amp;amp; rm -rf /var/lib/apt/lists/*
RUN npm install -g @anthropic-ai/claude-code
USER node
RUN mkdir -p /home/node/.claude
ENV CLAUDE_CONFIG_DIR=/home/node/.claude
WORKDIR /workspace
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Save it as &lt;code&gt;Dockerfile&lt;/code&gt;, then build it and run it from your project folder:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;docker build &lt;span class="nt"&gt;-t&lt;/span&gt; claude-sandbox &lt;span class="nb"&gt;.&lt;/span&gt;
docker run &lt;span class="nt"&gt;-it&lt;/span&gt; &lt;span class="nt"&gt;--rm&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$PWD&lt;/span&gt;&lt;span class="s2"&gt;:/workspace"&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt; claude-config:/home/node/.claude claude-sandbox claude
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In PowerShell, write &lt;code&gt;${PWD}&lt;/code&gt; instead of &lt;code&gt;$PWD&lt;/code&gt;. The first time, Claude Code asks you to sign in. Per Anthropic's dev container docs, if no browser opens inside the container, copy the login URL it prints into your browser and paste the code back; Bedrock, Vertex and Foundry users pass cloud credentials as environment variables instead. For an unattended run, end the command with &lt;code&gt;claude --dangerously-skip-permissions&lt;/code&gt; instead of &lt;code&gt;claude&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;What I checked in it:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It runs as a non-root user.&lt;/strong&gt; &lt;code&gt;id&lt;/code&gt; printed &lt;code&gt;node uid=1000&lt;/code&gt;, and &lt;code&gt;claude --version&lt;/code&gt; printed &lt;code&gt;2.1.314 (Claude Code)&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Claude Code's config survives restarts.&lt;/strong&gt; The &lt;code&gt;claude-config&lt;/code&gt; named volume kept what Claude Code wrote to &lt;code&gt;~/.claude&lt;/code&gt; (&lt;code&gt;projects&lt;/code&gt;, &lt;code&gt;sessions&lt;/code&gt;, &lt;code&gt;backups&lt;/code&gt;, &lt;code&gt;plugins&lt;/code&gt;) across separate containers. I didn't sign in, but per the docs the sign-in is stored there too. Setting &lt;code&gt;CLAUDE_CONFIG_DIR&lt;/code&gt; matters: without it, &lt;code&gt;~/.claude.json&lt;/code&gt; stays in the home folder and is lost with the container.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The project is shared both ways.&lt;/strong&gt; A file written to &lt;code&gt;/workspace&lt;/code&gt; inside the container appeared in my project folder on the host. That's the point, and also the risk: anything Claude deletes in &lt;code&gt;/workspace&lt;/code&gt; is deleted on your disk.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The image is big:&lt;/strong&gt; 1.18 GB. If disk space is tight, remove it with &lt;code&gt;docker rmi claude-sandbox&lt;/code&gt; when you're done, and the login with &lt;code&gt;docker volume rm claude-config&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  &lt;code&gt;--dangerously-skip-permissions cannot be used with root/sudo privileges&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;Claude Code 2.1.314 printed &lt;code&gt;--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons&lt;/code&gt; when I ran &lt;code&gt;claude --dangerously-skip-permissions&lt;/code&gt; as root in a plain &lt;code&gt;node&lt;/code&gt; container. Per Anthropic's docs, it refuses the flag as root on Linux and macOS. Docker containers run as root unless you change the user, which is why the Dockerfile in this section has &lt;code&gt;USER node&lt;/code&gt;. Run as the &lt;code&gt;node&lt;/code&gt; user, the same command got past that check and stopped only at &lt;code&gt;Not logged in · Please run /login&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is --dangerously-skip-permissions safe?
&lt;/h3&gt;

&lt;p&gt;Only inside an isolation boundary: a container, a VM, or the sandbox runtime (&lt;code&gt;srt claude&lt;/code&gt;). The built-in Bash sandbox alone isn't enough, because Claude's file tools, MCP servers and hooks run outside it. Even in a container, the mounted project can be changed, and with the flag on, Anthropic's dev container docs warn that a malicious project can send out anything the container can read, "including the Claude Code credentials stored in &lt;code&gt;~/.claude&lt;/code&gt;". Restrict network egress if you run code you don't trust.&lt;/p&gt;

&lt;h3&gt;
  
  
  Claude Code in a dev container
&lt;/h3&gt;

&lt;p&gt;If you use VS Code dev containers or GitHub Codespaces, Anthropic publishes a Dev Container Feature that installs Claude Code. A minimal &lt;code&gt;.devcontainer/devcontainer.json&lt;/code&gt; with a non-root user and the config kept in a volume, built from the examples in Anthropic's &lt;a href="https://code.claude.com/docs/en/devcontainer" rel="noopener noreferrer"&gt;dev container docs&lt;/a&gt; (I didn't build this one; the plain Docker route is the one I tested):&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"image"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"mcr.microsoft.com/devcontainers/base:ubuntu"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"features"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"ghcr.io/anthropics/devcontainer-features/claude-code:1.0"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{}&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"remoteUser"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"vscode"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"mounts"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"source=claude-code-config,target=/home/vscode/.claude,type=volume"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"containerEnv"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"CLAUDE_CONFIG_DIR"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"/home/vscode/.claude"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then run &lt;strong&gt;Dev Containers: Rebuild Container&lt;/strong&gt; and start &lt;code&gt;claude&lt;/code&gt; in the container's terminal. &lt;code&gt;remoteUser&lt;/code&gt; must be a non-root account for &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt; to start. For untrusted code, Anthropic's &lt;a href="https://github.com/anthropics/claude-code/tree/main/.devcontainer" rel="noopener noreferrer"&gt;reference dev container&lt;/a&gt; adds an &lt;code&gt;init-firewall.sh&lt;/code&gt; script that allows only approved destinations, with the &lt;code&gt;NET_ADMIN&lt;/code&gt; and &lt;code&gt;NET_RAW&lt;/code&gt; capabilities it needs.&lt;/p&gt;

&lt;p&gt;Two other Docker products come up in the same searches: &lt;a href="https://docs.docker.com/ai/sandboxes/" rel="noopener noreferrer"&gt;Docker Sandboxes&lt;/a&gt;, which Anthropic's docs describe as a microVM that can run Claude Code without Docker Desktop, and Docker's MCP Toolkit, which is about adding MCP servers to Claude Code rather than isolating it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Does the Claude Code sandbox work inside Docker?
&lt;/h2&gt;

&lt;p&gt;Not in a default container, in my test. On Docker Desktop, with the sandbox runtime 0.0.81 and bubblewrap 0.8.0 in &lt;code&gt;node:22-bookworm-slim&lt;/code&gt;, bubblewrap couldn't create its namespaces, because Docker's default seccomp profile blocks them for unprivileged processes. &lt;code&gt;--security-opt seccomp=unconfined&lt;/code&gt; let it start. The sandbox runtime uses the same bubblewrap as Claude Code's built-in sandbox on Linux; I couldn't run a signed-in Claude Code session in the test container, so these results are bubblewrap's behaviour, not a Claude Code session's.&lt;/p&gt;

&lt;p&gt;In a &lt;strong&gt;default&lt;/strong&gt; Docker container, as the non-root &lt;code&gt;node&lt;/code&gt; user, every sandboxed command failed with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;bwrap: No permissions to create new namespace, likely because the kernel does not allow non-privileged user namespaces.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Setting the runtime's &lt;code&gt;enableWeakerNestedSandbox&lt;/code&gt; option to &lt;code&gt;true&lt;/code&gt; (Claude Code exposes the same setting as &lt;code&gt;sandbox.enableWeakerNestedSandbox&lt;/code&gt;), which Anthropic's docs suggest for a different in-container error (&lt;code&gt;Can't mount proc&lt;/code&gt;), made no difference. The block comes from Docker's default seccomp profile, which doesn't let an unprivileged process create user namespaces.&lt;/p&gt;

&lt;p&gt;The sandbox runtime failed closed: it refused to run each command at all. Claude Code's built-in sandbox doesn't, by default. Per Anthropic's docs, when the sandbox can't start, Claude Code "runs commands without sandboxing", so a container plus &lt;code&gt;/sandbox&lt;/code&gt; can leave you with no inner sandbox and only a startup warning that's easy to miss. &lt;code&gt;"failIfUnavailable": true&lt;/code&gt; turns that into a startup error.&lt;/p&gt;

&lt;p&gt;With &lt;code&gt;--security-opt seccomp=unconfined&lt;/code&gt; on &lt;code&gt;docker run&lt;/code&gt;, bubblewrap started, and these were the results:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Command, run inside the sandbox&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rm -rf /home/node/precious&lt;/code&gt; (outside the project)&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Blocked:&lt;/strong&gt; &lt;code&gt;rm: cannot remove '/home/node/precious/data.txt': Read-only file system&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;The same delete from inside a &lt;code&gt;node -e&lt;/code&gt; script&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Blocked:&lt;/strong&gt; the script failed and the folder survived&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;sh -c "echo 20; rm -rf /home/node/precious"&lt;/code&gt; (modelled on the payload from &lt;a href="https://github.com/anthropics/claude-code/issues/105342" rel="noopener noreferrer"&gt;issue #105342&lt;/a&gt;)&lt;/td&gt;
&lt;td&gt;Printed &lt;code&gt;20&lt;/code&gt;, then the delete was &lt;strong&gt;blocked&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Write a file inside the project&lt;/td&gt;
&lt;td&gt;Allowed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rm -rf&lt;/code&gt; a folder inside the project&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Allowed&lt;/strong&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;fetch("https://example.com")&lt;/code&gt; with no allowed domains&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Blocked:&lt;/strong&gt; &lt;code&gt;EAI_AGAIN&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;So once bubblewrap can start, it enforces those limits, at least through the sandbox runtime I tested. But &lt;code&gt;seccomp=unconfined&lt;/code&gt; removes a protection from the container itself, so for most people the better choice is to treat &lt;strong&gt;the container as the boundary&lt;/strong&gt; and leave the inner sandbox off. If you do want both, Anthropic's fix for unprivileged containers is &lt;code&gt;enableWeakerNestedSandbox&lt;/code&gt;; in my Docker Desktop setup the seccomp profile was the blocker first.&lt;/p&gt;

&lt;h2&gt;
  
  
  Claude Code sandbox runtime (&lt;code&gt;srt claude&lt;/code&gt;)
&lt;/h2&gt;

&lt;p&gt;The Claude Code sandbox runtime is Anthropic's open-source tool for sandboxing the whole Claude Code process, not just its shell commands: start Claude Code with &lt;code&gt;srt claude&lt;/code&gt;, and file tools, MCP servers and hooks run inside the boundary too, without Docker. The package is &lt;a href="https://github.com/anthropics/sandbox-runtime" rel="noopener noreferrer"&gt;&lt;code&gt;@anthropic-ai/sandbox-runtime&lt;/code&gt;&lt;/a&gt;, a beta; I tested 0.0.81. Install it with &lt;code&gt;npm install -g @anthropic-ai/sandbox-runtime&lt;/code&gt;, set the boundary in &lt;code&gt;~/.srt-settings.json&lt;/code&gt;, and run &lt;code&gt;srt claude&lt;/code&gt; from your project folder:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"filesystem"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"denyRead"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[],&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"allowWrite"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"~/.claude"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"~/.claude.json"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"/tmp"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"denyWrite"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"network"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"allowedDomains"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"api.anthropic.com"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"claude.ai"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"platform.claude.com"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Claude Code needs to write its own config (&lt;code&gt;~/.claude&lt;/code&gt;, &lt;code&gt;~/.claude.json&lt;/code&gt;) and its temp folder (&lt;code&gt;/tmp&lt;/code&gt; on Linux and WSL2, &lt;code&gt;/private/tmp&lt;/code&gt; on macOS), and to reach the API and sign-in domains; an API-key login can drop the two &lt;code&gt;claude&lt;/code&gt; domains. On Linux, create the config paths before the first run, because the runtime only grants writes to paths that already exist. Two cautions from Anthropic's docs: it's a &lt;strong&gt;beta research preview&lt;/strong&gt;, and if &lt;code&gt;~/.srt-settings.json&lt;/code&gt; is missing it still starts, with built-in defaults, so a clean start doesn't prove your settings loaded.&lt;/p&gt;

&lt;h2&gt;
  
  
  When the Claude Code sandbox isn't working
&lt;/h2&gt;

&lt;p&gt;Usually either &lt;code&gt;bubblewrap&lt;/code&gt; or &lt;code&gt;socat&lt;/code&gt; is missing, or user namespaces are blocked (Docker's seccomp profile, or AppArmor on Ubuntu 24.04 and later). When the sandbox can't start, Claude Code runs commands unsandboxed unless &lt;code&gt;sandbox.failIfUnavailable&lt;/code&gt; is &lt;code&gt;true&lt;/code&gt;, so check this first if a sandboxed setup seems too permissive.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;Why&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;/sandbox&lt;/code&gt; shows only a Dependencies tab&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;bubblewrap&lt;/code&gt; or &lt;code&gt;socat&lt;/code&gt; missing (Linux, WSL2)&lt;/td&gt;
&lt;td&gt;Install them, restart Claude Code&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bwrap: No permissions to create new namespace&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;User namespaces blocked: Docker's seccomp profile, or AppArmor on Ubuntu 24.04+&lt;/td&gt;
&lt;td&gt;Container: rely on the container, or &lt;code&gt;seccomp=unconfined&lt;/code&gt;. Ubuntu: the AppArmor profile from the docs&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bwrap: Can't mount proc on /newroot/proc: Operation not permitted&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Unprivileged container&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;"enableWeakerNestedSandbox": true&lt;/code&gt;, only when the container is your real boundary&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;Sandboxing requires WSL2&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;WSL1&lt;/td&gt;
&lt;td&gt;Convert the distribution to WSL2&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Commands work but can reach anything&lt;/td&gt;
&lt;td&gt;The sandbox didn't start and Claude Code fell back&lt;/td&gt;
&lt;td&gt;Set &lt;code&gt;"failIfUnavailable": true&lt;/code&gt;, then check &lt;code&gt;/sandbox&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A build fails to download packages&lt;/td&gt;
&lt;td&gt;The domain isn't in &lt;code&gt;allowedDomains&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Add it, or approve it when asked&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A tool needs to write outside the project, such as &lt;code&gt;~/.kube&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Writes are limited by default&lt;/td&gt;
&lt;td&gt;Add the path to &lt;code&gt;sandbox.filesystem.allowWrite&lt;/code&gt; rather than excluding the tool&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;h2&gt;
  
  
  Recent sandbox fixes worth updating for
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.299&lt;/td&gt;
&lt;td&gt;Sandboxed commands on WSL2 no longer fail with &lt;code&gt;bwrap: Can't mkdir /mnt/c/Program Files/ClaudeCode&lt;/code&gt;; on macOS, a denied path can no longer be read or written through its real location behind a symlink&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.305&lt;/td&gt;
&lt;td&gt;New &lt;code&gt;sandbox.allowNestedUserNamespaces&lt;/code&gt;, for tools such as Chromium or rootless podman, at the cost of weakening the sandbox's file protections&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.309&lt;/td&gt;
&lt;td&gt;Sandboxed commands no longer run the shell's startup files outside the sandbox before each command; Linux write denies no longer lift when a background command outlives the session&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.310&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/sandbox&lt;/code&gt; names Ubuntu's AppArmor restriction, and how to lift it, when it keeps bubblewrap from starting&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.314&lt;/td&gt;
&lt;td&gt;Sandbox protections now apply to a worktree entered with &lt;code&gt;claude -p --resume&lt;/code&gt; or &lt;code&gt;--continue&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Turn on the Claude Code sandbox with /sandbox, or sandbox.enabled in ~/.claude/settings.json. It runs on macOS, Linux and WSL2, not native Windows.&lt;/li&gt;
&lt;li&gt;It covers shell commands and every process they start, so a delete inside a test or script is stopped outside the project. It doesn't cover Claude's file tools, MCP servers, hooks, or files inside the project.&lt;/li&gt;
&lt;li&gt;Set failIfUnavailable: true. By default, when the sandbox can't start, Claude Code runs commands unsandboxed.&lt;/li&gt;
&lt;li&gt;For --dangerously-skip-permissions, run Claude Code in a container as a non-root user. As root it refuses: 'cannot be used with root/sudo privileges for security reasons'.&lt;/li&gt;
&lt;li&gt;In my sandbox runtime test in a default Docker container, bubblewrap couldn't start ('No permissions to create new namespace'). Treat the container as the boundary rather than relying on /sandbox inside it.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;If Claude Code has already deleted something, &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;Claude Code deleted my files&lt;/a&gt; covers getting it back, and &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;the full list of Claude Code errors and fixes&lt;/a&gt; covers everything else. My &lt;a href="https://tools.its-tahir.com/claude-code-settings" rel="noopener noreferrer"&gt;Claude Code settings builder&lt;/a&gt; writes the sandbox block for you, and the &lt;a href="https://tools.its-tahir.com/guides/claude-code-subagents" rel="noopener noreferrer"&gt;subagents guide&lt;/a&gt; covers scoping what each agent can touch. Setting up coding agents to run unattended safely is part of the work I do: &lt;a href="https://www.its-tahir.com/work" rel="noopener noreferrer"&gt;see recent projects&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Does Claude Code have a sandbox?
&lt;/h3&gt;

&lt;p&gt;Yes. Claude Code has a built-in sandbox for shell commands. Run /sandbox in a session, or set sandbox.enabled to true in ~/.claude/settings.json. It limits Bash, PowerShell and Monitor commands, and every process they start, to writing inside your project, a temp folder and directories you added, and routes network traffic through a proxy that allows only the domains you approve. It runs on macOS, Linux and WSL2.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I enable the sandbox in Claude Code?
&lt;/h3&gt;

&lt;p&gt;Run /sandbox and pick a mode on the Mode tab: auto-allow runs sandboxed commands without prompting, regular permissions keeps the prompts. That saves to the project's .claude/settings.local.json. To turn it on for every project, set sandbox.enabled to true in ~/.claude/settings.json. On Linux and WSL2, install bubblewrap and socat first; on macOS there's nothing to install.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does the Claude Code sandbox work on Windows?
&lt;/h3&gt;

&lt;p&gt;Not on native Windows: there, Claude Code runs commands unsandboxed. Run Claude Code inside WSL2, where the sandbox works once bubblewrap and socat are installed, or run it in a Docker container, a dev container or a VM. Docker Desktop on Windows is enough for the container route.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does the Claude Code sandbox work inside Docker?
&lt;/h3&gt;

&lt;p&gt;Not in a default Docker container. In my test on Docker Desktop, using the sandbox runtime 0.0.81 rather than a signed-in Claude Code session, bubblewrap failed with 'No permissions to create new namespace', with or without enableWeakerNestedSandbox, because Docker's default seccomp profile blocks the user namespaces it needs. It worked with --security-opt seccomp=unconfined, but that weakens the container. Since Claude Code runs commands unsandboxed when the sandbox can't start, set sandbox.failIfUnavailable to true, or treat the container as the boundary.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I run Claude Code in Docker?
&lt;/h3&gt;

&lt;p&gt;Build an image that installs Claude Code with npm install -g @anthropic-ai/claude-code and switches to a non-root user, then run it with your project mounted, for example docker run -it --rm -v "$PWD:/workspace" -v claude-config:/home/node/.claude your-image claude (in PowerShell, use ${PWD}). Keep Claude Code's config, including the sign-in, in a named volume and set CLAUDE_CONFIG_DIR to it. The mounted project folder stays writable, so commit before long runs.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does --dangerously-skip-permissions say it cannot be used with root?
&lt;/h3&gt;

&lt;p&gt;Claude Code refuses the flag when it runs as root on Linux and macOS, with the message '--dangerously-skip-permissions cannot be used with root/sudo privileges for security reasons'. Docker containers run as root unless you change the user. Add USER node (or another non-root user) to your Dockerfile, or set remoteUser in a dev container.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is it safe to use --dangerously-skip-permissions?
&lt;/h3&gt;

&lt;p&gt;Only inside an isolation boundary: a container, a VM, or the sandbox runtime (srt claude). The built-in Bash sandbox alone isn't enough, because Claude's file tools, MCP servers and hooks run outside it. Even in a container, the mounted project can be changed and anything inside the container, including the Claude Code login, can be sent out unless you restrict network egress.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the difference between the sandbox and the sandbox runtime?
&lt;/h3&gt;

&lt;p&gt;The built-in sandbox wraps each shell command Claude runs. The sandbox runtime, the open source @anthropic-ai/sandbox-runtime package, wraps the whole Claude Code process when you start it with srt claude, so file tools, MCP servers and hooks are inside the boundary too. Both use bubblewrap on Linux and WSL2 and Seatbelt on macOS. The runtime is a beta research preview.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I check that commands really run sandboxed?
&lt;/h3&gt;

&lt;p&gt;Ask Claude to run touch ~/sandbox-probe. Inside the sandbox it fails with 'Read-only file system' on Linux and WSL2, or 'Operation not permitted' on macOS. Typing the command yourself at the ! prompt doesn't test it, because those commands usually run outside the sandbox. If Claude offers to retry outside the sandbox, decline.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/sandboxing" rel="noopener noreferrer"&gt;Configure the sandboxed Bash tool (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/sandbox-environments" rel="noopener noreferrer"&gt;Choose a sandbox environment (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/devcontainer" rel="noopener noreferrer"&gt;Development containers (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/permission-modes" rel="noopener noreferrer"&gt;Permission modes: bypassPermissions and actions no mode auto-approves (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/settings-reference" rel="noopener noreferrer"&gt;Settings reference: sandbox settings (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/sandbox-runtime" rel="noopener noreferrer"&gt;anthropics/sandbox-runtime README&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/tree/main/.devcontainer" rel="noopener noreferrer"&gt;Reference dev container: devcontainer.json, Dockerfile, init-firewall.sh (anthropics/claude-code)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (2.1.299 to 2.1.314)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://docs.docker.com/ai/sandboxes/" rel="noopener noreferrer"&gt;Docker Sandboxes (Docker docs)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-sandbox" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>docker</category>
      <category>ai</category>
      <category>security</category>
      <category>claudecode</category>
    </item>
    <item>
      <title>I tested how to get back files Claude Code deleted: /rewind can't undo an rm</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Fri, 30 Oct 2026 04:51:40 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-tested-how-to-get-back-files-claude-code-deleted-rewind-cant-undo-an-rm-12g9</link>
      <guid>https://dev.to/its-tahir/i-tested-how-to-get-back-files-claude-code-deleted-rewind-cant-undo-an-rm-12g9</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;After a Claude Code subagent ran rm -rf ~ from inside a test last week (issue #105342), I went through every place deleted files can still be and tested each one: the checkpoint copies in ~/.claude/file-history, Git (including staged-but-never-committed files), and your editor's local history. Then I checked which Claude Code protection actually stops which kind of delete, and wrote a guard hook that I tested against 18 commands. The short version: deny rules and hooks only read the command Claude types, so a delete hidden in a script gets past them. What's your setup, and has Claude Code ever deleted something of yours?&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If Anthropic's Claude Code just deleted your files, press &lt;code&gt;Esc&lt;/code&gt; to stop it, then run &lt;code&gt;/rewind&lt;/code&gt;: it restores files Claude changed with its own edit tools. It can't bring back a file that was only removed by a shell command such as &lt;code&gt;rm&lt;/code&gt;, so for those look in &lt;code&gt;~/.claude/file-history/&lt;/code&gt;, Git, your editor's local history and your backups, in that order.&lt;/strong&gt; Then lock it down, because the usual advice (a deny rule for &lt;code&gt;rm&lt;/code&gt;) misses most of the ways it happens.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What was deleted&lt;/th&gt;
&lt;th&gt;Where to look first&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Files Claude had been editing&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/rewind&lt;/code&gt;, then &lt;strong&gt;Restore code&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Files &lt;code&gt;rm&lt;/code&gt; or a script removed&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;~/.claude/file-history/&lt;/code&gt; (only if Claude edited them earlier), then Git&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Committed files, or commits lost to &lt;code&gt;git reset --hard&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;git restore&lt;/code&gt;, &lt;code&gt;git reflog&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Files you'd &lt;code&gt;git add&lt;/code&gt;-ed but never committed&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;git restore&lt;/code&gt;, or &lt;code&gt;git fsck --lost-found&lt;/code&gt; once unstaged&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Untracked files you'd opened in VS Code or JetBrains&lt;/td&gt;
&lt;td&gt;The editor's &lt;strong&gt;Local History&lt;/strong&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Anything else, including &lt;code&gt;.git&lt;/code&gt; itself&lt;/td&gt;
&lt;td&gt;Backups, then the remote&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A database&lt;/td&gt;
&lt;td&gt;Your provider's point-in-time restore&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;em&gt;Last checked 30 October 2026, against the Claude Code docs and changelog up to 2.1.314. Every recovery command and the hook below were tested first on my own Windows 11 machine, in Git Bash with Git 2.54.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What to do right after Claude Code deletes files
&lt;/h2&gt;

&lt;p&gt;Press &lt;code&gt;Esc&lt;/code&gt; to interrupt Claude, or &lt;code&gt;Ctrl+C&lt;/code&gt; to exit. Speed matters: in a September 2026 incident where Claude Code deleted 48,218 files, the whole delete took 103 seconds. Don't ask Claude to recreate the files yet, because that writes new files over the old ones. Then stop writing to the disk you lost files on until you've tried the steps below. Every new file can overwrite the blocks an undelete tool would need.&lt;/p&gt;

&lt;p&gt;Shell deletes skip the bin. &lt;code&gt;rm&lt;/code&gt; on macOS and Linux, &lt;code&gt;rm&lt;/code&gt; in Git Bash and &lt;code&gt;Remove-Item&lt;/code&gt; in PowerShell all delete permanently, so the Recycle Bin or Trash will usually be empty.&lt;/p&gt;

&lt;h2&gt;
  
  
  Can /rewind restore files Claude Code deleted?
&lt;/h2&gt;

&lt;p&gt;Only files Claude Code changed with its own Edit, Write or NotebookEdit tools. A file removed only by a shell command such as &lt;code&gt;rm&lt;/code&gt; was never checkpointed, so &lt;code&gt;/rewind&lt;/code&gt; can't restore it.&lt;/p&gt;

&lt;p&gt;Run &lt;code&gt;/rewind&lt;/code&gt;, or press &lt;code&gt;Esc&lt;/code&gt; twice with an empty prompt. Pick the prompt before the damage and choose &lt;strong&gt;Restore code&lt;/strong&gt; (keeps the conversation) or &lt;strong&gt;Restore code and conversation&lt;/strong&gt;.&lt;/p&gt;

&lt;p&gt;It covers less than its name suggests. Per the &lt;a href="https://code.claude.com/docs/en/checkpointing" rel="noopener noreferrer"&gt;checkpointing docs&lt;/a&gt;:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Tracked:&lt;/strong&gt; files Claude changed with its file tools (Edit, Write, NotebookEdit), and later shell changes to those same files.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Not tracked:&lt;/strong&gt; a file that "only Bash commands changed". If Claude never edited it, &lt;code&gt;rm&lt;/code&gt; deleting it leaves nothing to rewind.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Not restored:&lt;/strong&gt; edits by a subagent running in the background, including background forked skills.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Skipped:&lt;/strong&gt; symlinked and hard-linked files, with a &lt;code&gt;Restored the code, but skipped N files&lt;/code&gt; warning.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Gone after about 30 days:&lt;/strong&gt; the snapshots are deleted in Claude Code's retention sweep, and rewinding then fails with &lt;code&gt;No files were restored&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If the menu only offers &lt;strong&gt;Restore conversation&lt;/strong&gt;, the checkpoint has no tracked file changes, which usually means the files went through the shell. Try the checkpoint folder next.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why /rewind isn't working
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The menu offers only Restore conversation:&lt;/strong&gt; no file Claude edited changed after that prompt, so there's nothing to restore. Shell-only deletes look like this.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;No files were restored&lt;/code&gt;:&lt;/strong&gt; the snapshots were removed by the retention sweep, about 30 days after the session last saved one. Raise &lt;code&gt;cleanupPeriodDays&lt;/code&gt; to keep them longer.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Some files came back, others didn't:&lt;/strong&gt; a background subagent made the missing changes, or the files are symlinks or hard links, which rewind skips.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Find deleted files in Claude Code's checkpoint folder
&lt;/h2&gt;

&lt;p&gt;The snapshots behind &lt;code&gt;/rewind&lt;/code&gt; are ordinary files, and you can read them without the menu. That helps when the session is gone, or when Claude edited a file in an earlier prompt before deleting it.&lt;/p&gt;

&lt;p&gt;They live in &lt;code&gt;~/.claude/file-history/&amp;lt;session-id&amp;gt;/&lt;/code&gt;. On my Windows machine on 30 October 2026, that folder held 40 sessions and 39 MB of snapshots. Each file is a full plain copy, named with a hash and a version, such as &lt;code&gt;1d9a83bb87b6a918@v2&lt;/code&gt;. I checked one against the post it came from, and apart from line endings it was identical.&lt;/p&gt;

&lt;p&gt;To find a lost file, search for a line you remember from it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-rl&lt;/span&gt; &lt;span class="s2"&gt;"a line you remember from the lost file"&lt;/span&gt; ~/.claude/file-history/
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then open each match and copy back the one you want. The highest &lt;code&gt;@vN&lt;/code&gt; for a hash is its newest version. In PowerShell:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight powershell"&gt;&lt;code&gt;&lt;span class="n"&gt;Get-ChildItem&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="bp"&gt;$HOME&lt;/span&gt;&lt;span class="s2"&gt;\.claude\file-history"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;-Recurse&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;-File&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;Select-String&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nt"&gt;-List&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"a line you remember"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="o"&gt;|&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="n"&gt;Select-Object&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nx"&gt;Path&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This only finds files Claude edited with its file tools at some point. A file it never touched was never copied here.&lt;/p&gt;

&lt;h2&gt;
  
  
  Recover deleted files with Git
&lt;/h2&gt;

&lt;p&gt;What Git can give back depends on how far the file got. I tested each case in a scratch repository: created files in different states, ran &lt;code&gt;rm -rf&lt;/code&gt; on all of them, then tried to get them back.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;State of the file before &lt;code&gt;rm -rf&lt;/code&gt;
&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Committed&lt;/td&gt;
&lt;td&gt;Back, as of the &lt;strong&gt;last commit&lt;/strong&gt;. Later edits are lost&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git restore &amp;lt;path&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Staged with &lt;code&gt;git add&lt;/code&gt;, never committed&lt;/td&gt;
&lt;td&gt;Back, from the index&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git restore &amp;lt;path&amp;gt;&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Staged, then unstaged too&lt;/td&gt;
&lt;td&gt;Back, as a dangling blob&lt;/td&gt;
&lt;td&gt;&lt;code&gt;git fsck --lost-found&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Untracked, never added&lt;/td&gt;
&lt;td&gt;Gone. Git never saw it&lt;/td&gt;
&lt;td&gt;none&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;code&gt;git fsck --lost-found&lt;/code&gt; writes each orphaned file into &lt;code&gt;.git/lost-found/other/&lt;/code&gt;, named by hash and without its file name, so you identify them by content.&lt;/p&gt;

&lt;p&gt;If Claude ran &lt;code&gt;git reset --hard&lt;/code&gt; and your commits seem gone, they aren't. In my test, after &lt;code&gt;git reset --hard HEAD~2&lt;/code&gt; the reflog still listed both "lost" commits, and this brought them back:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;git reflog                      &lt;span class="c"&gt;# find the line before "reset: moving to"&lt;/span&gt;
git reset &lt;span class="nt"&gt;--hard&lt;/span&gt; &lt;span class="s1"&gt;'HEAD@{1}'&lt;/span&gt;     &lt;span class="c"&gt;# or the hash from that line&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;None of this works if &lt;code&gt;.git&lt;/code&gt; itself was deleted, which is why Git couldn't help in the 48,000-file case. Then your only copy is the remote: clone it again, and you lose only what wasn't pushed.&lt;/p&gt;

&lt;h2&gt;
  
  
  Restore untracked files from your editor's local history
&lt;/h2&gt;

&lt;p&gt;VS Code and JetBrains IDEs keep their own copies of files you saved in them, separate from Git and from Claude Code. That's the best chance for untracked files.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;VS Code:&lt;/strong&gt; open the &lt;strong&gt;Timeline&lt;/strong&gt; view in the Explorer for a file that still exists, or run &lt;strong&gt;Local History: Find Entry to Restore&lt;/strong&gt; from the Command Palette for one that doesn't. The copies are in &lt;code&gt;%APPDATA%\Code\User\History&lt;/code&gt; on Windows (I checked: one folder per file, with an &lt;code&gt;entries.json&lt;/code&gt; naming the original path), &lt;code&gt;~/Library/Application Support/Code/User/History&lt;/code&gt; on macOS and &lt;code&gt;~/.config/Code/User/History&lt;/code&gt; on Linux.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;JetBrains IDEs:&lt;/strong&gt; right-click the project folder and choose &lt;strong&gt;Local History&lt;/strong&gt;, then &lt;strong&gt;Show History&lt;/strong&gt;. Deleted files are listed there too.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Backups, and a deleted database
&lt;/h2&gt;

&lt;p&gt;After that, it's your normal backups: Time Machine on macOS, File History or "Previous Versions" on Windows, or snapshots on Linux filesystems that have them. A file-recovery tool is the last resort, and it only works if you stopped writing to the disk.&lt;/p&gt;

&lt;p&gt;For a database, Claude Code can't help: recovery is your provider's point-in-time restore or your own dumps. In the case &lt;a href="https://www.tomshardware.com/tech-industry/artificial-intelligence/claude-code-deletes-developers-production-setup-including-its-database-and-snapshots-2-5-years-of-records-were-nuked-in-an-instant" rel="noopener noreferrer"&gt;Tom's Hardware reported in March 2026&lt;/a&gt;, the snapshots went with the database, which is why a backup has to live somewhere the same credentials can't delete.&lt;/p&gt;

&lt;h2&gt;
  
  
  Can Claude Code delete files outside your project?
&lt;/h2&gt;

&lt;p&gt;Yes. Claude Code runs shell commands as your OS user, so a script or test it writes can delete anything you can, including your home folder. In each reported case below, the delete was inside a script, not a command anyone would have reviewed.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;48,218 files lost in 103 seconds&lt;/strong&gt; (&lt;a href="https://tech.yahoo.com/ai/claude/articles/48-000-files-deleted-103-135359723.html" rel="noopener noreferrer"&gt;TechRadar, September 2026&lt;/a&gt;). Asked to rebuild a mirror of a project, Claude Code wrote its own cleanup script. The script protected linked folders at the top level but not the folders nested under them. It deleted 55,550 files, restored 7,332 from an old copy (a net loss of 48,218), and took the &lt;code&gt;.git&lt;/code&gt; folder's &lt;code&gt;objects&lt;/code&gt;, &lt;code&gt;refs&lt;/code&gt; and &lt;code&gt;logs&lt;/code&gt; with it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;rm -rf ~&lt;/code&gt; from a test&lt;/strong&gt; (&lt;a href="https://github.com/anthropics/claude-code/issues/105342" rel="noopener noreferrer"&gt;issue #105342&lt;/a&gt;, 27 October 2026, Claude Code 2.1.311). A subagent running with &lt;code&gt;isolation: "worktree"&lt;/code&gt; wrote a test that passed the argument &lt;code&gt;20; rm -rf ~&lt;/code&gt; to a shell fixture. &lt;code&gt;cargo test&lt;/code&gt; ran it with the real &lt;code&gt;$HOME&lt;/code&gt;, and over about six minutes, before it was stopped, it deleted the project, its worktrees, other projects next to it and &lt;code&gt;~/.config&lt;/code&gt;. The &lt;code&gt;rm -rf ~&lt;/code&gt; never appeared in a tool call.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;kill(-1, SIGKILL)&lt;/code&gt; from a script&lt;/strong&gt; (&lt;a href="https://github.com/anthropics/claude-code/issues/104156" rel="noopener noreferrer"&gt;issue #104156&lt;/a&gt;). Not files, but the same mechanism: a placeholder PID of &lt;code&gt;-1&lt;/code&gt; in a Node script killed every process the user owned, including every other Claude Code session.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Worktree isolation gives a subagent its own Git checkout. It doesn't limit which files a process can reach, which is what the reporter of #105342 assumed.&lt;/p&gt;

&lt;h2&gt;
  
  
  What each protection actually stops
&lt;/h2&gt;

&lt;p&gt;A delete reaches your disk three ways: a command Claude types in a Bash call, a command inside a script or test it runs, or its own Write and Edit tools. Claude Code has six places you can stop one, and they catch different kinds. This is what each covers, from the docs and my own tests:&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fszpk1vdu28ljw3zzo8rx.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fszpk1vdu28ljw3zzo8rx.png" alt="Which Claude Code protection stops which delete. Deny or ask rule Bash(rm *): partly stops a delete Claude types in Bash (misses /bin/rm and bash -c), misses a delete inside a script or test, misses Write and Edit outside the project. Built-in critical-path check: partly stops typed deletes of /, ~, drives and the project folder, misses script deletes (issue #105342), misses Write and Edit. PreToolUse hook: stops what its patterns match, misses deletes inside scripts such as cargo test, covers Write and Edit only with an Edit|Write matcher. permissions.blockWritesOutsideWorkingDirectories (2.1.314+): only stops Claude's file tools outside the project. Bash sandbox on macOS, Linux and WSL2: stops shell deletes outside the project, including child processes, but not the file tools. Container, VM or separate user: stops all three outside the mounted folder. A script deleting files inside the project gets past all six." width="800" height="778"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;No single layer covers all three kinds of delete. The sandbox is the only one that sees inside scripts, and nothing protects the project folder from a script.&lt;/em&gt;&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Deny and ask rules&lt;/strong&gt; match the command text. The &lt;a href="https://code.claude.com/docs/en/permissions#what-a-bash-rule-doesnt-match" rel="noopener noreferrer"&gt;permissions docs&lt;/a&gt; say outright that &lt;code&gt;Bash(rm *)&lt;/code&gt; stops &lt;code&gt;rm -rf build/&lt;/code&gt; but not &lt;code&gt;/bin/rm -rf build/&lt;/code&gt; or &lt;code&gt;bash -c 'rm -rf build/'&lt;/code&gt;, and that a Bash rule "isn't a security boundary around the program".&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The critical-path check&lt;/strong&gt; is built in and always on. A recognised &lt;code&gt;rm&lt;/code&gt; or &lt;code&gt;rmdir&lt;/code&gt; of &lt;code&gt;/&lt;/code&gt;, your home folder, a drive, a mounted volume or the working directory itself prompts or is denied in every mode, &lt;code&gt;bypassPermissions&lt;/code&gt; included: no allow rule approves it. In the VS Code panel and the desktop app, where there's no terminal prompt, auto and bypass modes deny it. Like rules, it only sees the command text.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A &lt;code&gt;PreToolUse&lt;/code&gt; hook&lt;/strong&gt; reads the same text, but with your own logic, and it runs before your allow rules. Good for patterns rules can't express. Blind to scripts.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;permissions.blockWritesOutsideWorkingDirectories&lt;/code&gt;&lt;/strong&gt;, added in 2.1.314, makes Write, Edit and NotebookEdit refuse paths outside your working directories in every mode. Shell commands aren't covered.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The Bash sandbox&lt;/strong&gt; is enforced by the operating system, so it holds for child processes: test runners, build scripts, &lt;code&gt;node&lt;/code&gt; scripts. By default, sandboxed commands can write only to the working directory, a temp folder and directories you added. It doesn't cover Claude's file tools, and it doesn't run on native Windows.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A container, VM or separate OS user&lt;/strong&gt; puts all of Claude Code behind one boundary. It's the only option that also covers the file tools, MCP servers and hooks.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  How to stop Claude Code deleting files: sandbox, permissions and hooks
&lt;/h2&gt;

&lt;p&gt;Turn on the Bash sandbox with &lt;code&gt;allowUnsandboxedCommands: false&lt;/code&gt;, so shell commands and their child processes can only write inside the project. Set &lt;code&gt;permissions.blockWritesOutsideWorkingDirectories&lt;/code&gt; (Claude Code 2.1.314+) for Claude's own file tools. Add &lt;code&gt;ask&lt;/code&gt; rules for &lt;code&gt;rm&lt;/code&gt;, &lt;code&gt;git reset&lt;/code&gt;, &lt;code&gt;git clean&lt;/code&gt; and force pushes. All of it goes in &lt;code&gt;~/.claude/settings.json&lt;/code&gt;, so it applies to every project:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"permissions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"ask"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"Bash(rm *)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"Bash(git reset *)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"Bash(git clean *)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"Bash(git push --force *)"&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"deny"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Read(./.env)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Read(./.env.*)"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"blockWritesOutsideWorkingDirectories"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;},&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"sandbox"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"enabled"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"allowUnsandboxedCommands"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;What each line does:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;ask&lt;/code&gt; rules&lt;/strong&gt; make Claude stop and show you the command. &lt;code&gt;ask&lt;/code&gt; rather than &lt;code&gt;deny&lt;/code&gt; so you can still approve a cleanup you asked for. An ask rule also prompts in auto mode, and beats a broader allow rule.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;Read&lt;/code&gt; deny rules&lt;/strong&gt; keep Claude's file tools away from your &lt;code&gt;.env&lt;/code&gt; files, so production credentials aren't one read away. The docs note a &lt;code&gt;Read&lt;/code&gt; deny also blocks Edit and Write on the same path.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;blockWritesOutsideWorkingDirectories&lt;/code&gt;&lt;/strong&gt; needs Claude Code 2.1.314 or later. It's newer than the settings reference: as of 30 October 2026, the reference documents only its read-side partner, &lt;code&gt;blockReadsOutsideWorkingDirectories&lt;/code&gt;, so check &lt;code&gt;claude --version&lt;/code&gt; first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;sandbox.enabled&lt;/code&gt;&lt;/strong&gt; turns the sandbox on. You can also run &lt;code&gt;/sandbox&lt;/code&gt; in a session to try it first. &lt;code&gt;allowUnsandboxedCommands: false&lt;/code&gt; removes the escape hatch where Claude retries a failed command outside the sandbox.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you use auto mode, &lt;code&gt;/permissions&lt;/code&gt; has a &lt;strong&gt;Recently blocked&lt;/strong&gt; tab listing the calls it stopped. If you'd rather edit settings in a form than in JSON, my &lt;a href="https://tools.its-tahir.com/claude-code-settings" rel="noopener noreferrer"&gt;Claude Code settings builder&lt;/a&gt; writes the same keys.&lt;/p&gt;

&lt;h3&gt;
  
  
  A hook for what rules can't express
&lt;/h3&gt;

&lt;p&gt;Rules can't say "recursive &lt;code&gt;rm&lt;/code&gt; is fine on &lt;code&gt;node_modules&lt;/code&gt; but nowhere else". A hook can. This one is a Node script, so it runs the same on Windows, macOS and Linux without &lt;code&gt;jq&lt;/code&gt;. Save it as &lt;code&gt;.claude/hooks/guard-destructive.mjs&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight typescript"&gt;&lt;code&gt;&lt;span class="c1"&gt;// PreToolUse hook: stop shell commands that delete or reset a lot at once.&lt;/span&gt;
&lt;span class="c1"&gt;// Exit 2 blocks the call and shows Claude the reason on stderr.&lt;/span&gt;
&lt;span class="kd"&gt;let&lt;/span&gt; &lt;span class="nx"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="k"&gt;await &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;chunk&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nx"&gt;stdin&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nx"&gt;raw&lt;/span&gt; &lt;span class="o"&gt;+=&lt;/span&gt; &lt;span class="nx"&gt;chunk&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;command&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;JSON&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;parse&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;raw&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nx"&gt;tool_input&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nx"&gt;command&lt;/span&gt; &lt;span class="o"&gt;??&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="c1"&gt;// rm -rf on these folders stays allowed, so normal cleanup still works.&lt;/span&gt;
&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;SAFE&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;(\.\/)?(&lt;/span&gt;&lt;span class="sr"&gt;node_modules|dist|build|out|coverage|&lt;/span&gt;&lt;span class="se"&gt;\.&lt;/span&gt;&lt;span class="sr"&gt;next|&lt;/span&gt;&lt;span class="se"&gt;\.&lt;/span&gt;&lt;span class="sr"&gt;turbo|target&lt;/span&gt;&lt;span class="se"&gt;)\/?&lt;/span&gt;&lt;span class="sr"&gt;$/&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kd"&gt;function&lt;/span&gt; &lt;span class="nf"&gt;recursiveRmIsUnsafe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;cmd&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="k"&gt;for &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;part&lt;/span&gt; &lt;span class="k"&gt;of&lt;/span&gt; &lt;span class="nx"&gt;cmd&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/&amp;amp;&amp;amp;|&lt;/span&gt;&lt;span class="se"&gt;\|\|&lt;/span&gt;&lt;span class="sr"&gt;|&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;;|&lt;/span&gt;&lt;span class="se"&gt;\n]&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;words&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;part&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;trim&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="nf"&gt;split&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+/&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;words&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;findIndex&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;w&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;^|&lt;/span&gt;&lt;span class="se"&gt;\/)&lt;/span&gt;&lt;span class="sr"&gt;rm$/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;w&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;args&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;words&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;slice&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;i&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;recursive&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;args&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;some&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="sr"&gt;/^-&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;a-zA-Z&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;*&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;rR&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nx"&gt;a&lt;/span&gt; &lt;span class="o"&gt;===&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;--recursive&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;targets&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nx"&gt;args&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;filter&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;a&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;startsWith&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;-&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;recursive&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt;&lt;span class="nx"&gt;targets&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;every&lt;/span&gt;&lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;SAFE&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;/^&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;"'&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;|&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;"'&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;$/g&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;""&lt;/span&gt;&lt;span class="p"&gt;))))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
  &lt;span class="p"&gt;}&lt;/span&gt;
  &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;RULES&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b(&lt;/span&gt;&lt;span class="sr"&gt;bash|sh|zsh&lt;/span&gt;&lt;span class="se"&gt;)\s&lt;/span&gt;&lt;span class="sr"&gt;+-c&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;.*&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;rm&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;rm inside sh -c&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;git&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+clean&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+-&lt;/span&gt;&lt;span class="se"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;a-zA-Z&lt;/span&gt;&lt;span class="se"&gt;]&lt;/span&gt;&lt;span class="sr"&gt;*f/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;git clean -f&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;git&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+reset&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+--hard&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;git reset --hard&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;git&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;checkout|restore&lt;/span&gt;&lt;span class="se"&gt;)\s&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;--&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;)?\.(\s&lt;/span&gt;&lt;span class="sr"&gt;|$&lt;/span&gt;&lt;span class="se"&gt;)&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;discarding every uncommitted change&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;git&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+push&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;.*&lt;/span&gt;&lt;span class="se"&gt;\s(&lt;/span&gt;&lt;span class="sr"&gt;--force|-f&lt;/span&gt;&lt;span class="se"&gt;)\b&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;git push --force&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;find&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;.*&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;-delete&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;find -delete&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;Remove-Item&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;.*-Recurse/i&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;Remove-Item -Recurse&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b(&lt;/span&gt;&lt;span class="sr"&gt;drop&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+&lt;/span&gt;&lt;span class="se"&gt;(&lt;/span&gt;&lt;span class="sr"&gt;database|schema|table&lt;/span&gt;&lt;span class="se"&gt;)&lt;/span&gt;&lt;span class="sr"&gt;|truncate&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+table&lt;/span&gt;&lt;span class="se"&gt;)\b&lt;/span&gt;&lt;span class="sr"&gt;/i&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;dropping database objects&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
  &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;terraform&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+destroy&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;|&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;kubectl&lt;/span&gt;&lt;span class="se"&gt;\s&lt;/span&gt;&lt;span class="sr"&gt;+delete&lt;/span&gt;&lt;span class="se"&gt;\b&lt;/span&gt;&lt;span class="sr"&gt;/&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;destroying infrastructure&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;
&lt;span class="p"&gt;];&lt;/span&gt;

&lt;span class="kd"&gt;const&lt;/span&gt; &lt;span class="nx"&gt;reason&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;recursiveRmIsUnsafe&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;command&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
  &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="dl"&gt;"&lt;/span&gt;&lt;span class="s2"&gt;recursive rm outside the allowed build folders&lt;/span&gt;&lt;span class="dl"&gt;"&lt;/span&gt;
  &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="nx"&gt;RULES&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;find&lt;/span&gt;&lt;span class="p"&gt;(([&lt;/span&gt;&lt;span class="nx"&gt;re&lt;/span&gt;&lt;span class="p"&gt;])&lt;/span&gt; &lt;span class="o"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nx"&gt;re&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;test&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;command&lt;/span&gt;&lt;span class="p"&gt;))?.[&lt;/span&gt;&lt;span class="mi"&gt;1&lt;/span&gt;&lt;span class="p"&gt;];&lt;/span&gt;

&lt;span class="k"&gt;if &lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nx"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;
  &lt;span class="nx"&gt;console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;error&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s2"&gt;`Blocked by the guard-destructive hook (&lt;/span&gt;&lt;span class="p"&gt;${&lt;/span&gt;&lt;span class="nx"&gt;reason&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;). Don't retry it another way: show the command to the user and ask them to run it.`&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
  &lt;span class="nx"&gt;process&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;exit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;2&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Register it in the project's &lt;code&gt;.claude/settings.json&lt;/code&gt;, next to the script, and commit both so everyone on the project gets it. Registering it in &lt;code&gt;~/.claude/settings.json&lt;/code&gt; instead would make it fail in every project that doesn't have the file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"hooks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"PreToolUse"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"matcher"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Bash|PowerShell"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"hooks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
          &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
            &lt;/span&gt;&lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"command"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
            &lt;/span&gt;&lt;span class="nl"&gt;"command"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"node"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
            &lt;/span&gt;&lt;span class="nl"&gt;"args"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-destructive.mjs"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
          &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;I tested the script by piping it the same JSON Claude Code sends (&lt;code&gt;{"tool_input":{"command":"..."}}&lt;/code&gt;) for 18 commands:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Command&lt;/th&gt;
&lt;th&gt;Result&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rm -rf node_modules dist&lt;/code&gt;, &lt;code&gt;rm -rf ./build/&lt;/code&gt;, &lt;code&gt;rm file.txt&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Allowed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rm -rf ~&lt;/code&gt;, &lt;code&gt;rm -rf src&lt;/code&gt;, &lt;code&gt;rm -fr ../other-project&lt;/code&gt;, &lt;code&gt;/bin/rm -r data&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Blocked&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;npm test &amp;amp;&amp;amp; rm -Rf "$HOME/.config"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Blocked (each part of a chain is checked)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;bash -c 'rm -rf build'&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Blocked&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;git clean -fdx&lt;/code&gt;, &lt;code&gt;git reset --hard HEAD~3&lt;/code&gt;, &lt;code&gt;git checkout -- .&lt;/code&gt;, &lt;code&gt;git push --force origin main&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Blocked&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;find . -name "*.log" -delete&lt;/code&gt;, &lt;code&gt;psql -c "DROP TABLE users"&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Blocked&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;git push origin main&lt;/code&gt;, &lt;code&gt;npm run build&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Allowed&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cargo test&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Allowed&lt;/strong&gt;, and it would run any &lt;code&gt;rm -rf ~&lt;/code&gt; hidden in a test&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;That last row is the gap: a hook only sees what Claude types. To build a hook like this without writing JSON by hand, try the &lt;a href="https://tools.its-tahir.com/claude-code-hooks-builder" rel="noopener noreferrer"&gt;Claude Code hooks builder&lt;/a&gt;; the &lt;a href="https://tools.its-tahir.com/guides/claude-code-hooks" rel="noopener noreferrer"&gt;hooks guide&lt;/a&gt; explains the events.&lt;/p&gt;

&lt;h3&gt;
  
  
  The rest of the checklist
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Commit and push before long runs.&lt;/strong&gt; It's the only protection for files inside the project, and the remote is the only copy a delete inside &lt;code&gt;.git&lt;/code&gt; can't reach.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Don't run &lt;code&gt;--dangerously-skip-permissions&lt;/code&gt; on your own machine.&lt;/strong&gt; It skips prompts, including for writes to &lt;code&gt;.git&lt;/code&gt; and &lt;code&gt;.claude&lt;/code&gt;. The critical-path &lt;code&gt;rm&lt;/code&gt; prompt survives, but &lt;code&gt;CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1&lt;/code&gt; (2.1.311+) turns even that off. The docs' advice is a container or VM "where Claude Code cannot damage your host system".&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Treat subagents as unsupervised.&lt;/strong&gt; Their edits aren't in your checkpoints, and &lt;code&gt;isolation: "worktree"&lt;/code&gt; isn't a sandbox. My &lt;a href="https://tools.its-tahir.com/guides/claude-code-subagents" rel="noopener noreferrer"&gt;subagents guide&lt;/a&gt; covers scoping their tools.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use plan mode for anything destructive.&lt;/strong&gt; Ask for the plan, read the commands, then let it run. See the &lt;a href="https://tools.its-tahir.com/guides/claude-code-plan-mode" rel="noopener noreferrer"&gt;plan mode guide&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Have test fixtures set &lt;code&gt;HOME&lt;/code&gt; to a temp folder&lt;/strong&gt;, as a commenter on #105342 suggested, so a stray &lt;code&gt;~&lt;/code&gt; in a test never reaches your real home.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep production credentials out of reach.&lt;/strong&gt; If Claude can read them, a command it runs can use them. Give it a read-only database user, and keep admin credentials and the right to delete backups in a different account.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Does the Claude Code sandbox work on Windows?
&lt;/h2&gt;

&lt;p&gt;No. Claude Code's Bash sandbox runs on macOS, Linux and WSL2; on native Windows, Anthropic's docs say "Claude Code runs commands unsandboxed". To get it, run Claude Code inside WSL2 or a dev container.&lt;/p&gt;

&lt;p&gt;Native Windows still has the PowerShell tool's own guards. &lt;code&gt;Remove-Item&lt;/code&gt; on the filesystem root, a drive root, top-level system folders or your home folder is denied in every mode without asking, and so is a bare &lt;code&gt;*&lt;/code&gt; wildcard. Since 2.1.283, so are &lt;code&gt;cmd /c rd&lt;/code&gt;, &lt;code&gt;rmdir&lt;/code&gt;, &lt;code&gt;del&lt;/code&gt; and &lt;code&gt;erase&lt;/code&gt; on the same paths. A recursive &lt;code&gt;Remove-Item&lt;/code&gt; of your working directory or one of its parents goes through the normal permission prompt.&lt;/p&gt;

&lt;p&gt;The 48,000-file case involved Windows junction folders, so test any cleanup script that walks linked folders before it runs for real.&lt;/p&gt;

&lt;h2&gt;
  
  
  Recent fixes worth updating for
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.281&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;rm -rf "$(pwd)"&lt;/code&gt; and other removals whose target is only command-substitution output now ask, even with a Bash allow rule&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.287&lt;/td&gt;
&lt;td&gt;A dangerous &lt;code&gt;rm&lt;/code&gt; no longer loses its always-ask safeguard when the same command redirects output to &lt;code&gt;~&lt;/code&gt; or a wildcard path&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.288&lt;/td&gt;
&lt;td&gt;A dangerous &lt;code&gt;rm&lt;/code&gt; inside &lt;code&gt;bash -c&lt;/code&gt; or &lt;code&gt;sh -c&lt;/code&gt; no longer runs without a prompt in &lt;code&gt;bypassPermissions&lt;/code&gt; mode or under a shell allow rule&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.292&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;rm -rf&lt;/code&gt; on the 8.3 short name or another alternate Windows spelling of the home folder or a drive is now treated as removing it&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.296&lt;/td&gt;
&lt;td&gt;Windows: &lt;code&gt;rm -rf /c/Users/&amp;lt;name&amp;gt;&lt;/code&gt; in Git Bash now asks in bypass permissions mode&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.304&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;rm -r&lt;/code&gt; of a mounted drive or a folder at its top level (&lt;code&gt;/Volumes&lt;/code&gt;, &lt;code&gt;/media&lt;/code&gt;, WSL's &lt;code&gt;/mnt/c&lt;/code&gt;) now gets the safety prompt&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.314&lt;/td&gt;
&lt;td&gt;New &lt;code&gt;permissions.blockWritesOutsideWorkingDirectories&lt;/code&gt; for Write, Edit and NotebookEdit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;/rewind only restores files Claude changed with its own edit tools. A file only rm touched was never tracked, and background subagent edits aren't restored.&lt;/li&gt;
&lt;li&gt;Checkpoint snapshots are plain copies in ~/.claude/file-history//. grep -rl a line you remember to find a lost file, within about 30 days.&lt;/li&gt;
&lt;li&gt;Git recovers committed and staged files (git restore), unstaged blobs (git fsck --lost-found) and commits lost to git reset --hard (git reflog). Untracked files need your editor's Local History or a backup.&lt;/li&gt;
&lt;li&gt;Deny rules, the critical-path check and hooks all read the command Claude sends. A delete inside a script or test gets past them; only the sandbox, a container or a separate user limits it.&lt;/li&gt;
&lt;li&gt;Turn on the sandbox with allowUnsandboxedCommands false, set blockWritesOutsideWorkingDirectories (2.1.314+), add ask rules for rm and git reset, and push before long runs.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;If the delete came with an auto mode message instead, &lt;a href="https://www.its-tahir.com/blog/claude-code-auto-mode-classifier-no-verdict" rel="noopener noreferrer"&gt;auto mode gave no verdict&lt;/a&gt; explains the classifier side, and &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;the full list of Claude Code errors and fixes&lt;/a&gt; covers everything else. Setting up coding agents so they can work unattended without this kind of risk is part of the work I do: &lt;a href="https://www.its-tahir.com/work" rel="noopener noreferrer"&gt;see recent projects&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Can Claude Code delete files?
&lt;/h3&gt;

&lt;p&gt;Yes. Claude Code runs shell commands as your user, so anything you can delete, a command it runs can delete, including files outside the project. Permission prompts, the built-in check for dangerous rm commands, deny rules and hooks all look at the command Claude sends. A delete inside a script or test that Claude writes and then runs gets past all of them. Only the Bash sandbox (macOS, Linux and WSL2) or running Claude Code in a container, VM or separate user account limits what that script can reach.&lt;/p&gt;

&lt;h3&gt;
  
  
  Can /rewind restore files Claude Code deleted?
&lt;/h3&gt;

&lt;p&gt;Only some of them. /rewind restores files Claude changed with its own file tools (Edit, Write, NotebookEdit), plus later shell changes to those same files. A file that only a shell command such as rm touched was never tracked, so rewinding doesn't bring it back. Edits a background subagent made aren't restored either. For everything else, use Git, your editor's local history, or a backup.&lt;/p&gt;

&lt;h3&gt;
  
  
  Where does Claude Code keep checkpoint backups?
&lt;/h3&gt;

&lt;p&gt;In ~/.claude/file-history//. Each file there is a plain copy of a file Claude edited, named with a hash and a version, such as &lt;a href="mailto:1d9a83bb87b6a918@v2"&gt;1d9a83bb87b6a918@v2&lt;/a&gt;. Search them for a line you remember from the lost file with grep -rl. Claude Code deletes them in its retention sweep, by default about 30 days after the session last saved one; cleanupPeriodDays changes that.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I stop Claude Code from deleting files?
&lt;/h3&gt;

&lt;p&gt;Use several layers, because each one misses something. Turn on the Bash sandbox (/sandbox) so shell commands and their child processes can only write inside the project, and set allowUnsandboxedCommands to false. Set permissions.blockWritesOutsideWorkingDirectories to true (2.1.314+) for Claude's file tools. Add ask rules for rm, git reset, git clean and force pushes, and a PreToolUse hook for the patterns you care about. Commit and push often, because nothing on the list protects files inside the project from a script.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does a deny rule like Bash(rm *) stop every delete?
&lt;/h3&gt;

&lt;p&gt;No. A Bash rule matches the command text Claude writes. The docs list /bin/rm -rf build/ and bash -c 'rm -rf build/' as forms Bash(rm *) doesn't stop, and it can't see a delete inside a Python script, a test or a build tool. Use it as a speed bump, and use the sandbox when the limit has to hold.&lt;/p&gt;

&lt;h3&gt;
  
  
  Does the Claude Code sandbox work on Windows?
&lt;/h3&gt;

&lt;p&gt;Not natively. The sandbox runs on macOS, Linux and WSL2; on native Windows, Claude Code runs commands unsandboxed. Run Claude Code inside WSL2 or a dev container to get it. On native Windows you still have the PowerShell tool's own guards, which deny Remove-Item on system paths, the home folder and bare wildcards in every mode.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does permissions.blockWritesOutsideWorkingDirectories do?
&lt;/h3&gt;

&lt;p&gt;Added in Claude Code 2.1.314, it makes the Write, Edit and NotebookEdit tools refuse paths outside your working directories in every permission mode, including bypassPermissions. It doesn't cover shell commands, so an rm outside the project still depends on the sandbox, your rules and the critical-path check. It's the write-side partner of permissions.blockReadsOutsideWorkingDirectories.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is Claude Code safe to use?
&lt;/h3&gt;

&lt;p&gt;Safe enough with the Bash sandbox on and your work committed and pushed. Claude Code runs commands as your user, so treat what it runs like a script you didn't review: prompts and rules check the command it types, not what a script or test does once it runs. In both code-loss cases covered here, the work that was lost hadn't been pushed to a remote.&lt;/p&gt;

&lt;h3&gt;
  
  
  Is --dangerously-skip-permissions safe?
&lt;/h3&gt;

&lt;p&gt;Only in a container or VM you can afford to lose. It skips permission prompts, including for writes to .git and .claude. Recognised rm commands on critical paths such as / and your home folder still prompt in the terminal, and are denied in the VS Code panel and the desktop app, but CLAUDE_CODE_EVEN_MORE_DANGEROUSLY_SKIP_PERMISSIONS=1 removes even that, and nothing in this mode looks inside scripts.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/checkpointing" rel="noopener noreferrer"&gt;Checkpointing: what /rewind tracks and its limitations (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/claude-directory" rel="noopener noreferrer"&gt;Explore the .claude directory: file-history and the retention sweep (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/permissions" rel="noopener noreferrer"&gt;Configure permissions: deny rules and what a Bash rule doesn't match (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/permission-modes" rel="noopener noreferrer"&gt;Permission modes: protected paths, critical-path rm removals, Remove-Item in PowerShell (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/sandboxing" rel="noopener noreferrer"&gt;Configure the sandboxed Bash tool (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/settings-reference" rel="noopener noreferrer"&gt;Settings reference: permissions.blockReadsOutsideWorkingDirectories, sandbox settings (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/hooks-guide" rel="noopener noreferrer"&gt;Hooks guide: block an action with exit code 2 (Claude Code docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (2.1.281 to 2.1.314)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/105342" rel="noopener noreferrer"&gt;Subagent-written test ran rm -rf ~ on the real home directory; worktree isolation didn't contain it (anthropics/claude-code #105342)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/104156" rel="noopener noreferrer"&gt;Bash tool commands can signal every user process: kill(-1, SIGKILL) (anthropics/claude-code #104156)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://tech.yahoo.com/ai/claude/articles/48-000-files-deleted-103-135359723.html" rel="noopener noreferrer"&gt;48,000 files deleted in 103 seconds (TechRadar via Yahoo Tech, 25 September 2026)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://www.tomshardware.com/tech-industry/artificial-intelligence/claude-code-deletes-developers-production-setup-including-its-database-and-snapshots-2-5-years-of-records-were-nuked-in-an-instant" rel="noopener noreferrer"&gt;Claude Code deletes developer's production setup, including its database and snapshots (Tom's Hardware, March 2026)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-deleted-my-files" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>security</category>
      <category>ai</category>
      <category>programming</category>
      <category>claudecode</category>
    </item>
    <item>
      <title>I checked my Claude Code transcripts: 'compacting early' was idle compaction</title>
      <dc:creator>Tahir Nazir</dc:creator>
      <pubDate>Wed, 28 Oct 2026 13:18:31 +0000</pubDate>
      <link>https://dev.to/its-tahir/i-checked-my-claude-code-transcripts-compacting-early-was-idle-compaction-2hdn</link>
      <guid>https://dev.to/its-tahir/i-checked-my-claude-code-transcripts-compacting-early-was-idle-compaction-2hdn</guid>
      <description>&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;Last week two of my Claude Code sessions compacted at about 265K tokens on a 1M-token window. It looked like a regression, so I read the compaction records in my own transcripts. They told a different story, and it turns out 'Claude Code keeps compacting' is really four different problems with four different fixes. Has yours been compacting early too? I'd like to know which of the four it was.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;If Claude Code compacted far below the limit after you'd been away, that's idle compaction, not a lower threshold: it summarises a 200K+ token conversation before its one-hour cache expires, and &lt;code&gt;"idleCompaction": false&lt;/code&gt; turns it off.&lt;/strong&gt; If it keeps compacting for other reasons, it's one of these, and each needs a different fix:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;What you see&lt;/th&gt;
&lt;th&gt;What it is&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;It compacted far below the limit after you'd been away&lt;/td&gt;
&lt;td&gt;
&lt;strong&gt;Idle compaction&lt;/strong&gt;, not a lower threshold&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;"idleCompaction": false&lt;/code&gt; in settings.json&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;It compacts at the same low point every time, such as 200K&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;A small auto-compact window&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/autocompact auto&lt;/code&gt;, or unset &lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;It compacts, refills within a few turns, then stops with &lt;code&gt;Autocompact is thrashing&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Something refills the context&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;/context&lt;/code&gt;, then read files in chunks or trim what loads at startup&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;Prompt is too long&lt;/code&gt; instead of compacting, or a cloud session that loops&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;An open bug&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Resend the message, or start a new session&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;It never compacts and stops with &lt;code&gt;Context limit reached&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;&lt;strong&gt;Auto-compact is off&lt;/strong&gt;&lt;/td&gt;
&lt;td&gt;Turn &lt;strong&gt;Auto-compact&lt;/strong&gt; on in &lt;code&gt;/config&lt;/code&gt;, or unset &lt;code&gt;DISABLE_AUTO_COMPACT&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two commands tell you which one you have: &lt;code&gt;/context&lt;/code&gt; shows what's filling the window, and &lt;code&gt;/autocompact&lt;/code&gt; with no value shows the window your current model uses.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Last checked 28 October 2026, against Claude Code 2.1.312.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpuf63x1uzpip0a8s3rxw.png" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fpuf63x1uzpip0a8s3rxw.png" alt="Why Claude Code keeps compacting. One: compacted far below the limit after a break, notice Compacted while idle, before the prompt cache expired, or a summary written while you were away, transcript shows precomputed true: idle compaction, fix with idleCompaction false. Two: compacts at the same low point every time: a small auto-compact window from /autocompact, autoCompactWindow, --autocompact, CLAUDE_CODE_AUTO_COMPACT_WINDOW or CLAUDE_CODE_DISABLE_1M_CONTEXT; default on 1M models is about 967K; fix with /autocompact auto. Three: Autocompact is thrashing, the context refilled to the limit within 3 turns of the previous compact, 3 times in a row: a big file or tool output, re-injected CLAUDE.md and rules, or an MCP tool; run /context. Four: Prompt is too long or a cloud session loop: open bugs #104494 and #105086." width="800" height="800"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;Four things look like 'Claude Code keeps compacting'. Match the symptom first, because the fixes don't overlap.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  What my own sessions show
&lt;/h2&gt;

&lt;p&gt;Before writing this I read the compaction records in this machine's Claude Code transcripts. Every compaction writes a &lt;code&gt;compact_boundary&lt;/code&gt; line with its trigger and token counts, so you can see exactly when and why it ran. I read only that metadata, not the conversations.&lt;/p&gt;

&lt;p&gt;Every normal auto-compaction fired at the limit, between &lt;strong&gt;967,344 and 972,043 tokens&lt;/strong&gt;, on versions 2.1.292 to 2.1.310. That matches the documented default for 1M-context models, "about 967K tokens".&lt;/p&gt;

&lt;p&gt;Then on 27 October, in the VS Code extension on 2.1.310, two compactions marked &lt;code&gt;"trigger": "auto"&lt;/code&gt; fired at &lt;strong&gt;265,565&lt;/strong&gt; and &lt;strong&gt;263,336&lt;/strong&gt; tokens. Read by token count alone, that looks like auto-compact kicking in at a quarter of the window. It wasn't. Both records also carried &lt;code&gt;"precomputed": true&lt;/code&gt;, and both landed one to two seconds after I sent a message following a long break: about three hours the first time, about seven the second. That's idle compaction, which Anthropic has started rolling out to the VS Code chat panel and the desktop app's Code tab.&lt;/p&gt;

&lt;p&gt;People hit the same confusion in GitHub &lt;a href="https://github.com/anthropics/claude-code/issues/101067" rel="noopener noreferrer"&gt;issue #101067&lt;/a&gt;, which reported auto-compaction "at 281K to 845K tokens" as a regression. The reporter later confirmed every early compaction carried the line "Compacted while idle, before the prompt cache expired" and fired about 54 minutes after the last message.&lt;/p&gt;

&lt;p&gt;To check your own, run this in a terminal (macOS, Linux, or Git Bash on Windows). It prints the trigger and size of every compaction in your saved transcripts:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-rh&lt;/span&gt; &lt;span class="s1"&gt;'"compact_boundary"'&lt;/span&gt; ~/.claude/projects/ | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-oE&lt;/span&gt; &lt;span class="s1"&gt;'"(trigger|preTokens|precomputed)":[^,}]*'&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;On my machine it printed lines like &lt;code&gt;"trigger":"auto" "preTokens":265565 "precomputed":true&lt;/code&gt;. Any &lt;code&gt;precomputed: true&lt;/code&gt; entry is an idle compaction.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cause 1: idle compaction, after you've been away
&lt;/h2&gt;

&lt;p&gt;If the early compaction happened after a break, look for one of these notices:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Compacted while idle, before the prompt cache expired
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;





&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Compacted using a summary written while you were away · turn off with "idleCompaction": false in settings.json
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The first is the terminal's notice. The second appears in the VS Code chat panel and, inside a row labelled &lt;code&gt;Claude Code notice&lt;/code&gt;, in the desktop app.&lt;/p&gt;

&lt;p&gt;Idle compaction summarises a conversation of 200,000 tokens or more shortly before its one-hour prompt cache expires, so your next message doesn't pay to reprocess the whole history. It isn't a lower threshold, and changing the auto-compact window won't stop it. To turn it off:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"idleCompaction"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="kc"&gt;false&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;That needs Claude Code 2.1.290 or later. In the terminal, &lt;code&gt;/config&lt;/code&gt; has an &lt;strong&gt;Idle compaction&lt;/strong&gt; row from 2.1.302. &lt;a href="https://www.its-tahir.com/blog/claude-code-compacted-while-idle" rel="noopener noreferrer"&gt;The full guide to "Compacted while idle"&lt;/a&gt; covers the exact conditions, the new VS Code and desktop behaviour, and when it's worth leaving on.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cause 2: a small auto-compact window
&lt;/h2&gt;

&lt;p&gt;If it compacts at the same point every time, check the window. Run &lt;code&gt;/autocompact&lt;/code&gt; with no value. In a &lt;a href="https://github.com/anthropics/claude-code/issues/101067" rel="noopener noreferrer"&gt;report on issue #101067&lt;/a&gt;, the dialog showed &lt;code&gt;Current setting for Opus 5.5: 1m tokens (default for this model)&lt;/code&gt;, and pressing Esc left it &lt;code&gt;unchanged&lt;/code&gt;. That 1M is the window. On 1M models, compaction triggers a little under it, at about 967K.&lt;/p&gt;

&lt;p&gt;With no window set, Claude Code compacts at the model's context limit, with these exceptions from the &lt;a href="https://code.claude.com/docs/en/model-config" rel="noopener noreferrer"&gt;model configuration docs&lt;/a&gt;:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Session&lt;/th&gt;
&lt;th&gt;Compacts at&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Native 1M models: the Fable models, Sonnet 5 and later, Haiku 5.5, Opus 4.7 and later&lt;/td&gt;
&lt;td&gt;About 967K tokens&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Those models with &lt;code&gt;CLAUDE_CODE_DISABLE_1M_CONTEXT=1&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The 200K boundary&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Sonnet 4.6 and Opus 4.6 without extended context&lt;/td&gt;
&lt;td&gt;The 200K boundary&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A model ID Claude Code doesn't recognise, such as a gateway alias&lt;/td&gt;
&lt;td&gt;The window it assumes for that ID&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Cloud sessions&lt;/td&gt;
&lt;td&gt;As the conversation approaches the model's limit&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Four places can set a smaller window, from highest priority to lowest:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt;&lt;/strong&gt; environment variable. It overrides everything below, and while it's set, &lt;code&gt;/autocompact&lt;/code&gt; only reports it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;--autocompact&lt;/code&gt;&lt;/strong&gt; flag, for one launch: &lt;code&gt;claude --autocompact 500k&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;/autocompact &amp;lt;size&amp;gt;&lt;/code&gt;&lt;/strong&gt;, saved for the current model under &lt;code&gt;modelSettings&lt;/code&gt; in your user settings. Since 2.1.288 it's per model, so a window you set for Opus doesn't apply to Sonnet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;autoCompactWindow&lt;/code&gt;&lt;/strong&gt; in a settings file, for every model.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;All of them take 100K to 1M tokens, and Claude Code caps the value at the model's real window. To go back to the default for your model, run &lt;code&gt;/autocompact auto&lt;/code&gt;, and unset the environment variable if you have one.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The environment variable reads numbers differently.&lt;/strong&gt; In &lt;code&gt;/autocompact&lt;/code&gt; and &lt;code&gt;--autocompact&lt;/code&gt;, a bare &lt;code&gt;200&lt;/code&gt; means 200,000. In &lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt;, &lt;code&gt;200&lt;/code&gt; means 200 tokens, and Claude Code warns that it &lt;code&gt;reads as 200 tokens, so Claude Code treats it as the 100k minimum&lt;/code&gt;. Write &lt;code&gt;200000&lt;/code&gt;, or &lt;code&gt;200k&lt;/code&gt; on 2.1.304 or later. Before 2.1.304, &lt;code&gt;200k&lt;/code&gt; silently set a 100K window, per that release's changelog.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Why &lt;code&gt;CLAUDE_AUTOCOMPACT_PCT_OVERRIDE&lt;/code&gt; seems to do nothing.&lt;/strong&gt; The variable sets the percentage of the window at which compaction triggers, from 1 to 100. It can only lower the threshold: values above the default percentage are ignored. And the docs say it "applies only in sessions that compact before the model's context limit". A default session compacts at the limit, so there's nothing for the percentage to apply to.&lt;/p&gt;

&lt;p&gt;That's the long-running complaint in &lt;a href="https://github.com/anthropics/claude-code/issues/63186" rel="noopener noreferrer"&gt;issue #63186&lt;/a&gt;. A commenter there found it only worked once &lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt; was also set, with the trigger at roughly the window times the percentage: a 500,000 window at 60% compacted at about 300K. If you want to compact earlier, setting the window directly is simpler.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Want it later, not earlier?&lt;/strong&gt; On a 1M model you're already at about 967K. On a 200K model, the 200K boundary is the model's real limit, so there's no room to raise. If you use the settings builder on my tools site, &lt;a href="https://tools.its-tahir.com/claude-code-settings" rel="noopener noreferrer"&gt;it writes &lt;code&gt;autoCompactWindow&lt;/code&gt; and the rest of &lt;code&gt;settings.json&lt;/code&gt; for you&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cause 3: "Autocompact is thrashing"
&lt;/h2&gt;

&lt;p&gt;This is the full message:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Autocompact is thrashing: the context refilled to the limit within 3 turns of the previous compact, 3 times in a row. A file being read or a tool output is likely too large for the context window. Try reading in smaller chunks, or use /clear to start fresh.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Compaction didn't fail. It worked, and then the context filled straight back up, three times in a row, so Claude Code stopped instead of burning requests on a loop that isn't moving.&lt;/p&gt;

&lt;p&gt;Run &lt;code&gt;/context&lt;/code&gt; and compare the &lt;strong&gt;Messages&lt;/strong&gt; row with the rows above it. That's the docs' own test, and it splits the problem in two:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Messages is the largest row:&lt;/strong&gt; something in the conversation is refilling the window. Ask Claude to read the big file in chunks, a line range or one function, instead of the whole thing. Run &lt;code&gt;/compact&lt;/code&gt; with a focus that drops the large output, like &lt;code&gt;/compact keep only the plan and the diff&lt;/code&gt;. Move large-file work to a &lt;a href="https://tools.its-tahir.com/guides/claude-code-subagents" rel="noopener noreferrer"&gt;subagent&lt;/a&gt;, which has its own context window. To see how big a file is before Claude reads it, paste it into a &lt;a href="https://tools.its-tahir.com/token-counter" rel="noopener noreferrer"&gt;token counter&lt;/a&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The other rows together are larger:&lt;/strong&gt; what loads at session start leaves too little room to work. Trim it.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The message always blames "a file being read or a tool output", but the reports on GitHub show three other sources:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Re-injected instruction files.&lt;/strong&gt; In &lt;a href="https://github.com/anthropics/claude-code/issues/85489" rel="noopener noreferrer"&gt;issue #85489&lt;/a&gt;, no single file or output was large. A 248 KB set of &lt;code&gt;.claude/rules/*.md&lt;/code&gt; plus &lt;code&gt;CLAUDE.md&lt;/code&gt; was re-attached after each compaction, about 122K tokens in one turn on top of the post-compaction summary, which landed right back on the trigger. That session compacted 16 times in 1 hour 48 minutes. Smaller instruction files, or rules that load only when relevant, fix it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A window too small for your fixed context.&lt;/strong&gt; In &lt;a href="https://github.com/anthropics/claude-code/issues/100932" rel="noopener noreferrer"&gt;issue #100932&lt;/a&gt;, a 100K &lt;code&gt;autoCompactWindow&lt;/code&gt; with roughly 25K to 30K tokens of instructions and memory loaded every session left very little room. The session, and its subagents, thrashed after a few tool calls. The reporter also found the "3 turns" count model responses inside a tool loop, not your messages. If you've lowered the window, raise it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;An oversized MCP tool definition.&lt;/strong&gt; In &lt;a href="https://github.com/anthropics/claude-code/issues/102389" rel="noopener noreferrer"&gt;issue #102389&lt;/a&gt;, tool search pulled in an MCP tool whose input schema was about 2.99 MB. Every request went over the 1M limit, and because discovered tools survive compaction, the session couldn't recover. Fix or disconnect the server, then start a new session.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two recent releases fix cases you might be hitting. 2.1.307 fixed "some 'Autocompact is thrashing' errors in turns that read many PDF pages, images or other large tool results". 2.1.309 fixed sessions compacting repeatedly after reading files under a very large nested CLAUDE.md. If you're behind, update first.&lt;/p&gt;

&lt;h2&gt;
  
  
  Cause 4: open bugs that look like compaction trouble
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;Prompt is too long&lt;/code&gt; instead of compacting.&lt;/strong&gt; &lt;a href="https://github.com/anthropics/claude-code/issues/104494" rel="noopener noreferrer"&gt;Issue #104494&lt;/a&gt; traces this to the auto-compact check running before the turn's CLAUDE.md and memory attachments are added. The check sees room, the attachments push it over, and you get a local &lt;code&gt;Prompt is too long&lt;/code&gt; without a compaction. Resending the same message usually works, because the second attempt counts the attachment and compacts first.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A cloud session that refills after every compaction.&lt;/strong&gt; &lt;a href="https://github.com/anthropics/claude-code/issues/105086" rel="noopener noreferrer"&gt;Issue #105086&lt;/a&gt;, opened on 25 October, describes claude.ai/code sessions where each compaction freed about 83K tokens and the window was full again three or four tool calls later, until the session ended. The same prompts ran fine in the local CLI. It's open with no fix, so in a cloud session, push your work early.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The session stops after compacting.&lt;/strong&gt; In &lt;a href="https://github.com/anthropics/claude-code/issues/104920" rel="noopener noreferrer"&gt;issue #104920&lt;/a&gt;, the session went idle after an auto-compaction instead of starting the work Claude had just announced. Type "continue".&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Auto-compact not working: it never compacts
&lt;/h2&gt;

&lt;p&gt;The opposite problem. If Claude Code hits the limit without compacting, check three things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Is auto-compact off?&lt;/strong&gt; &lt;code&gt;"autoCompactEnabled": false&lt;/code&gt; in a settings file, or &lt;code&gt;DISABLE_AUTO_COMPACT=1&lt;/code&gt; in your environment. Either one keeps it off, and the other can't turn it back on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Did you get &lt;code&gt;Prompt is too long&lt;/code&gt; instead?&lt;/strong&gt; That's the &lt;a href="https://github.com/anthropics/claude-code/issues/104494" rel="noopener noreferrer"&gt;#104494&lt;/a&gt; ordering bug above. Resend the same message.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Did you set only &lt;code&gt;CLAUDE_AUTOCOMPACT_PCT_OVERRIDE&lt;/code&gt;?&lt;/strong&gt; On its own it does nothing in a default session. Set a window as well, or use &lt;code&gt;/autocompact&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Turning auto-compact off
&lt;/h2&gt;

&lt;p&gt;You can, but you'll trade compactions for hard stops. Switch &lt;strong&gt;Auto-compact&lt;/strong&gt; off in &lt;code&gt;/config&lt;/code&gt;, which writes &lt;code&gt;"autoCompactEnabled": false&lt;/code&gt;, or set &lt;code&gt;DISABLE_AUTO_COMPACT=1&lt;/code&gt;. Both also turn off idle compaction, and &lt;code&gt;/compact&lt;/code&gt; keeps working. When the window fills, Claude Code stops with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;DISABLE_COMPACT=1&lt;/code&gt; goes further and disables &lt;code&gt;/compact&lt;/code&gt; too, so &lt;code&gt;/clear&lt;/code&gt; is the only way forward. Since 2.1.311 it can only turn compaction off from a settings file, not back on.&lt;/p&gt;

&lt;p&gt;For most people the better move is narrower: &lt;code&gt;idleCompaction: false&lt;/code&gt; if the problem is compactions after breaks, or a larger window if you lowered it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Recent fixes worth updating for
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Version&lt;/th&gt;
&lt;th&gt;Fix&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2.1.304&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k&lt;/code&gt; no longer silently sets a 100K window, and out-of-range values now warn&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.307&lt;/td&gt;
&lt;td&gt;Fewer thrashing errors in turns that read many PDF pages, images or large tool results&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.309&lt;/td&gt;
&lt;td&gt;No more repeated compaction after reading files under a very large nested CLAUDE.md&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.310&lt;/td&gt;
&lt;td&gt;Compaction after a "Prompt is too long" error no longer keeps too much dense text such as base64 or SVG&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.311&lt;/td&gt;
&lt;td&gt;Claude no longer sees stale CLAUDE.md and MEMORY.md right after a compaction&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.311&lt;/td&gt;
&lt;td&gt;Standard-context sessions that ran over 200K tokens now compact instead of stopping with &lt;a href="https://tools.its-tahir.com/errors/usage-credits-required-1m-context" rel="noopener noreferrer"&gt;&lt;code&gt;Usage credits required for 1M context&lt;/code&gt;&lt;/a&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;2.1.312&lt;/td&gt;
&lt;td&gt;A subagent's &lt;code&gt;autoCompactWindow&lt;/code&gt; can now lower the window set by &lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;&lt;strong&gt;Key takeaways&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;'Claude Code keeps compacting' is four different problems: idle compaction, a small auto-compact window, something refilling the context, or an open bug. /context and /autocompact tell them apart.&lt;/li&gt;
&lt;li&gt;Compactions far below the limit after a break are idle compaction. The transcript marks them precomputed: true. Turn them off with idleCompaction: false.&lt;/li&gt;
&lt;li&gt;With no window set, 1M-context models compact at about 967K tokens. A window set by /autocompact, autoCompactWindow, --autocompact or CLAUDE_CODE_AUTO_COMPACT_WINDOW makes it compact earlier; /autocompact auto resets it.&lt;/li&gt;
&lt;li&gt;In CLAUDE_CODE_AUTO_COMPACT_WINDOW, 200 means 200 tokens. Write 200000 or 200k. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE can only lower a window that's already set.&lt;/li&gt;
&lt;li&gt;'Autocompact is thrashing' means compaction worked but the context refilled. If /context shows Messages as the largest row, read files in chunks; otherwise trim CLAUDE.md, rules and MCP tools.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;p&gt;For the cost side of long sessions, &lt;a href="https://www.its-tahir.com/blog/why-claude-code-uses-so-many-tokens" rel="noopener noreferrer"&gt;why Claude Code uses so many tokens&lt;/a&gt; breaks down where usage goes, and &lt;a href="https://www.its-tahir.com/blog/claude-code-troubleshooting" rel="noopener noreferrer"&gt;the full list of Claude Code errors and fixes&lt;/a&gt; covers everything else. Keeping long-running agent sessions on track across compactions is part of the work I do: &lt;a href="https://www.its-tahir.com/work" rel="noopener noreferrer"&gt;see recent projects&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  FAQ
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Why does Claude Code keep compacting?
&lt;/h3&gt;

&lt;p&gt;Usually one of four things. Idle compaction summarises a 200K+ token conversation you left for about an hour, far below the context limit. A small auto-compact window, set with /autocompact, autoCompactWindow, --autocompact or CLAUDE_CODE_AUTO_COMPACT_WINDOW, makes it compact at the same low point every time. Something refills the context right after each compaction, which ends in 'Autocompact is thrashing'. Or you hit an open bug. Run /context and /autocompact to see which.&lt;/p&gt;

&lt;h3&gt;
  
  
  What does 'Autocompact is thrashing' mean in Claude Code?
&lt;/h3&gt;

&lt;p&gt;Compaction worked, but the context refilled to the limit within 3 turns of the previous compaction, 3 times in a row, so Claude Code stopped retrying. The message blames a file or tool output, which is the usual cause, but re-injected CLAUDE.md and rules files, a small auto-compact window, or an oversized MCP tool definition can do it too. Run /context: if the Messages row is the largest, read files in chunks; if the other rows together are larger, trim what loads at startup.&lt;/p&gt;

&lt;h3&gt;
  
  
  What is the default auto-compact threshold in Claude Code?
&lt;/h3&gt;

&lt;p&gt;With no window set, Claude Code compacts at the model's context limit. Models with a native 1M window, such as the Fable models, Sonnet 5 and later, Haiku 5.5 and Opus 4.7 and later, compact at about 967K tokens. Sonnet 4.6 and Opus 4.6 without extended context, and 1M models with CLAUDE_CODE_DISABLE_1M_CONTEXT=1, compact at the 200K boundary. My own sessions on 1M models compacted between 967,344 and 972,043 tokens.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I change when Claude Code auto-compacts?
&lt;/h3&gt;

&lt;p&gt;Run /autocompact with a size such as /autocompact 500k, which saves the window for the current model, or /autocompact auto to go back to the default. You can also set autoCompactWindow in settings.json, pass --autocompact for one launch, or set CLAUDE_CODE_AUTO_COMPACT_WINDOW. The window must be between 100K and 1M tokens, and the environment variable overrides the others.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does CLAUDE_AUTOCOMPACT_PCT_OVERRIDE do nothing?
&lt;/h3&gt;

&lt;p&gt;It can only lower the threshold, and it applies only in sessions that compact before the model's context limit. A default session compacts at the limit, so the percentage has nothing to apply to. Set an auto-compact window, for example CLAUDE_CODE_AUTO_COMPACT_WINDOW=500000, or use /autocompact directly, which is simpler.&lt;/p&gt;

&lt;h3&gt;
  
  
  How do I turn off auto-compact in Claude Code?
&lt;/h3&gt;

&lt;p&gt;Switch Auto-compact off in /config, which writes autoCompactEnabled: false, or set DISABLE_AUTO_COMPACT=1. Both also turn off idle compaction and keep the manual /compact command. With it off, a full window stops the session with 'Context limit reached' until you run /compact or /clear. DISABLE_COMPACT=1 goes further and disables /compact too. To stop only the compactions after a break, set idleCompaction to false instead.&lt;/p&gt;

&lt;h3&gt;
  
  
  Why does CLAUDE_CODE_AUTO_COMPACT_WINDOW=200 not set 200K?
&lt;/h3&gt;

&lt;p&gt;In the environment variable, a number with no suffix means that many tokens, so 200 is 200 tokens, which Claude Code raises to the 100K minimum. Write 200000, or 200k on Claude Code 2.1.304 or later. The /autocompact command and --autocompact flag are different: there, a bare number from 100 to 1000 means thousands.&lt;/p&gt;

&lt;h2&gt;
  
  
  Sources
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/model-config" rel="noopener noreferrer"&gt;Model configuration: context window and auto-compaction — Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/troubleshooting" rel="noopener noreferrer"&gt;Troubleshooting: auto-compaction stops with a thrashing error — Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/settings-reference" rel="noopener noreferrer"&gt;Settings reference: autoCompactEnabled, autoCompactWindow, idleCompaction — Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/env-vars" rel="noopener noreferrer"&gt;Environment variables: CLAUDE_CODE_AUTO_COMPACT_WINDOW, CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, DISABLE_AUTO_COMPACT — Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/errors" rel="noopener noreferrer"&gt;Error reference: Context limit reached / Prompt is too long — Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md" rel="noopener noreferrer"&gt;Claude Code changelog (2.1.304 to 2.1.312)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/85489" rel="noopener noreferrer"&gt;Autocompact-thrashing warning blames 'a file or tool output' when the refill came from re-injected project instructions (anthropics/claude-code #85489)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/100932" rel="noopener noreferrer"&gt;Autocompact thrashing with a small autoCompactWindow (anthropics/claude-code #100932)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/101067" rel="noopener noreferrer"&gt;Auto-compaction fires at 281K to 845K tokens on 2.1.296 (anthropics/claude-code #101067)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/102389" rel="noopener noreferrer"&gt;ToolSearch loads an MCP tool bigger than the context window; auto-compact keeps it (anthropics/claude-code #102389)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/104494" rel="noopener noreferrer"&gt;Auto-compact is evaluated before turn-start attachments are appended (anthropics/claude-code #104494)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/105086" rel="noopener noreferrer"&gt;Cloud sessions: auto-compact thrash loop (anthropics/claude-code #105086)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/104920" rel="noopener noreferrer"&gt;Session goes idle after auto-compaction instead of continuing (anthropics/claude-code #104920)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/anthropics/claude-code/issues/63186" rel="noopener noreferrer"&gt;CLAUDE_AUTOCOMPACT_PCT_OVERRIDE in settings.json env block silently ignored (anthropics/claude-code #63186)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published at &lt;a href="https://www.its-tahir.com/blog/claude-code-keeps-compacting" rel="noopener noreferrer"&gt;its-tahir.com&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>productivity</category>
      <category>programming</category>
      <category>claudecode</category>
    </item>
  </channel>
</rss>
