<?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: Nixon Perinchery</title>
    <description>The latest articles on DEV Community by Nixon Perinchery (@nixonperinchery).</description>
    <link>https://dev.to/nixonperinchery</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%2F4208701%2F3dc40dc8-9e5d-4045-a6e7-7749199bc6a4.jpg</url>
      <title>DEV Community: Nixon Perinchery</title>
      <link>https://dev.to/nixonperinchery</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/nixonperinchery"/>
    <language>en</language>
    <item>
      <title>Codex Rules: Control Commands with prefix_rule</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Fri, 13 Nov 2026 17:29:44 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/codex-rules-control-commands-with-prefixrule-1o93</link>
      <guid>https://dev.to/nixonperinchery/codex-rules-control-commands-with-prefixrule-1o93</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Codex rules are .rules files that decide, per command prefix, whether a command runs without asking, asks first, or is blocked.&lt;/li&gt;
&lt;li&gt;When several rules match one command, the most restrictive wins: forbidden beats prompt, and prompt beats allow.&lt;/li&gt;
&lt;li&gt;Test rules with codex execpolicy check before relying on them, and put match and not_match examples in the rule so Codex validates them on load.&lt;/li&gt;
&lt;li&gt;Rules match an exact prefix of the command, so option order matters; shell scripts using redirection, substitution, variables or wildcards are judged as one whole command.&lt;/li&gt;
&lt;li&gt;Project rules in .codex/rules only load when the project's .codex layer is trusted, and the feature is marked experimental.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you want Codex to stop asking about commands you always approve, and to refuse commands you never want run, you write rules. Codex rules are small &lt;code&gt;.rules&lt;/code&gt; files that match a command's prefix and give it a decision: allow, prompt or forbidden. This guide shows where the files go, how &lt;code&gt;prefix_rule&lt;/code&gt; works, how to test a rule before trusting it, and where compound shell commands can surprise you.&lt;/p&gt;

&lt;p&gt;Everything about Codex behaviour below comes from OpenAI's &lt;a href="https://learn.chatgpt.com/docs/agent-configuration/rules" rel="noopener noreferrer"&gt;Codex rules documentation&lt;/a&gt;. The docs mark rules as experimental and subject to change, so re-check the page before you roll anything out to a team. The old &lt;a href="https://github.com/openai/codex/blob/main/docs/execpolicy.md" rel="noopener noreferrer"&gt;execpolicy page in the openai/codex repository&lt;/a&gt; is now only a pointer to the hosted docs.&lt;/p&gt;

&lt;h2&gt;
  
  
  What are Codex rules?
&lt;/h2&gt;

&lt;p&gt;Rules control which commands Codex can run outside the sandbox. They sit alongside the approval mode and sandbox you already configure: approval mode answers "how much does Codex ask in general", and rules answer "what about this specific command".&lt;/p&gt;

&lt;p&gt;A rule has three possible decisions:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;allow&lt;/code&gt;: the command runs without prompting.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;prompt&lt;/code&gt;: Codex asks before each matching run.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;forbidden&lt;/code&gt;: Codex blocks the request.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If you do not give a decision, the default is &lt;code&gt;allow&lt;/code&gt;. Keep that in mind when you copy a rule and forget the &lt;code&gt;decision&lt;/code&gt; line.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where do the rules files go?
&lt;/h2&gt;

&lt;p&gt;Create a &lt;code&gt;.rules&lt;/code&gt; file in a &lt;code&gt;rules/&lt;/code&gt; folder next to an active config layer. The documented example is &lt;code&gt;~/.codex/rules/default.rules&lt;/code&gt;. Codex scans the &lt;code&gt;rules/&lt;/code&gt; folder in every active config layer at startup, including Team Config locations and your user layer.&lt;/p&gt;

&lt;p&gt;Two details matter in practice:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Project-local rules in &lt;code&gt;&amp;lt;repo&amp;gt;/.codex/rules/&lt;/code&gt; load only when the project's &lt;code&gt;.codex/&lt;/code&gt; layer is trusted. A cloned repo you have not trusted will not silently apply its own rules.&lt;/li&gt;
&lt;li&gt;When you add a command to the allow list from the terminal UI, Codex writes it to &lt;code&gt;~/.codex/rules/default.rules&lt;/code&gt;. That file can grow without you editing it, so read it now and then.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Restart Codex after adding a rule.&lt;/p&gt;

&lt;p&gt;The format is Starlark, a Python-like language designed so that evaluating it has no side effects. A rules file can only describe matches.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you write a prefix_rule?
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;prefix_rule()&lt;/code&gt; takes these fields:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;pattern&lt;/code&gt; (required): a non-empty list. Each element is either a literal string or a list of alternatives for that argument position.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;decision&lt;/code&gt;: &lt;code&gt;allow&lt;/code&gt;, &lt;code&gt;prompt&lt;/code&gt; or &lt;code&gt;forbidden&lt;/code&gt;. Defaults to &lt;code&gt;allow&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;justification&lt;/code&gt;: a human-readable reason that can show up in approval prompts or rejection messages. For &lt;code&gt;forbidden&lt;/code&gt;, it can suggest an alternative.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;match&lt;/code&gt; and &lt;code&gt;not_match&lt;/code&gt;: lists of example commands that Codex validates when it loads the rules, to catch mistakes early.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This is the example from the documentation:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="nf"&gt;prefix_rule&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;pattern&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"gh"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"pr"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"view"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;decision&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"prompt"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;justification&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Viewing PRs is allowed with approval"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="s2"&gt;"gh pr view 7888"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"gh pr view --repo openai/codex"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"gh pr view 7888 --json title,body,comments"&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;not_match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="c1"&gt;# Does not match because the `pattern` must be an exact prefix.&lt;/span&gt;
        &lt;span class="s2"&gt;"gh pr --repo openai/codex view 7888"&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;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The comment in &lt;code&gt;not_match&lt;/code&gt; is the important lesson. The pattern is an exact prefix of the command's words. &lt;code&gt;gh pr --repo openai/codex view 7888&lt;/code&gt; is the same operation to a human, but the words are in a different order, so the rule does not match it. Write rules for the form your team actually types, and add the awkward orderings to &lt;code&gt;not_match&lt;/code&gt; so you can see the gap.&lt;/p&gt;

&lt;h3&gt;
  
  
  A forbidden rule with an alternative
&lt;/h3&gt;

&lt;p&gt;Here is a rule of the same shape that I wrote as an illustration, not one from the documentation. It blocks force pushes and uses alternatives at the last position of the pattern:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="nf"&gt;prefix_rule&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;pattern&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"git"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"push"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"--force"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"-f"&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;decision&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"forbidden"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;justification&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"Force pushes are blocked. Use a new commit or ask a maintainer."&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="s2"&gt;"git push --force"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="s2"&gt;"git push -f"&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;not_match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;
        &lt;span class="s2"&gt;"git push origin main"&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;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Notice what it does not catch. &lt;code&gt;git push origin --force&lt;/code&gt; has the flag after &lt;code&gt;origin&lt;/code&gt;, so this prefix does not match it. A rule like this is a speed bump for the common spelling, not a guarantee. For anything you truly cannot allow, combine rules with the sandbox and with branch protection on the server side.&lt;/p&gt;

&lt;h3&gt;
  
  
  Allowing the boring commands
&lt;/h3&gt;

&lt;p&gt;The other half of the job is trimming prompts. A read-only command you run all day is a good candidate:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight python"&gt;&lt;code&gt;&lt;span class="nf"&gt;prefix_rule&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="n"&gt;pattern&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"git"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"status"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;decision&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s2"&gt;"allow"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="k"&gt;match&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"git status"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s2"&gt;"git status --short"&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;Allow narrow prefixes. &lt;code&gt;["git", "status"]&lt;/code&gt; is a safer thing to approve than &lt;code&gt;["git"]&lt;/code&gt;, which would cover every Git subcommand.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you test rules before relying on them?
&lt;/h2&gt;

&lt;p&gt;Use &lt;code&gt;codex execpolicy check&lt;/code&gt; to see how your rules apply to a command:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 7888 --json title,body,comments
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pass &lt;code&gt;--rules&lt;/code&gt; more than once to combine files, which is how you can test a project rules file together with your personal one.&lt;/p&gt;

&lt;p&gt;A practical routine:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Write the rule with &lt;code&gt;match&lt;/code&gt; and &lt;code&gt;not_match&lt;/code&gt; examples, so Codex checks them when it loads the file.&lt;/li&gt;
&lt;li&gt;Run &lt;code&gt;codex execpolicy check&lt;/code&gt; on three or four real commands, including one you expect not to match.&lt;/li&gt;
&lt;li&gt;Restart Codex and try the command in a real session.&lt;/li&gt;
&lt;li&gt;Commit project rules only after a teammate has run the same check on their machine.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  What happens when two rules match?
&lt;/h2&gt;

&lt;p&gt;The most restrictive decision applies: &lt;code&gt;forbidden&lt;/code&gt; beats &lt;code&gt;prompt&lt;/code&gt;, and &lt;code&gt;prompt&lt;/code&gt; beats &lt;code&gt;allow&lt;/code&gt;. So you can allow a broad prefix and then add a stricter rule for a dangerous variant, and the stricter one wins. Admins can also enforce restrictive &lt;code&gt;prefix_rule&lt;/code&gt; entries through &lt;code&gt;requirements.toml&lt;/code&gt;, which gives a team a way to set limits that personal rules do not override.&lt;/p&gt;

&lt;h2&gt;
  
  
  Shell wrappers and compound commands
&lt;/h2&gt;

&lt;p&gt;Agents rarely run bare commands. They often run &lt;code&gt;bash -lc "..."&lt;/code&gt;. Codex treats &lt;code&gt;bash -c&lt;/code&gt;, &lt;code&gt;bash -lc&lt;/code&gt; and the &lt;code&gt;zsh&lt;/code&gt; and &lt;code&gt;sh&lt;/code&gt; equivalents specially, and the behaviour decides whether your rules protect you.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;If the script is a simple chain of plain words joined by &lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt;, &lt;code&gt;||&lt;/code&gt;, &lt;code&gt;;&lt;/code&gt; or &lt;code&gt;|&lt;/code&gt;, Codex splits it and evaluates each command separately. For example, &lt;code&gt;git add . &amp;amp;&amp;amp; rm -rf /&lt;/code&gt; is evaluated as &lt;code&gt;git add .&lt;/code&gt; and &lt;code&gt;rm -rf /&lt;/code&gt;, so allowing &lt;code&gt;git add&lt;/code&gt; does not allow the whole line.&lt;/li&gt;
&lt;li&gt;If the script uses redirection, substitution, environment variables, wildcards or control flow, Codex does not split it. It treats the whole invocation as one command and applies rules to that.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The second case is where allow rules get less useful. A line such as &lt;code&gt;git status &amp;gt; out.txt&lt;/code&gt; is one command to Codex, so check what your &lt;code&gt;["git", "status"]&lt;/code&gt; rule does with it using &lt;code&gt;codex execpolicy check&lt;/code&gt; rather than assuming. Test your real habitual command lines, not only the tidy ones.&lt;/p&gt;

&lt;h2&gt;
  
  
  Smart approvals and the allow list
&lt;/h2&gt;

&lt;p&gt;With Smart approvals, which are on by default per the docs, Codex may suggest a &lt;code&gt;prefix_rule&lt;/code&gt; when it escalates a command. That is convenient and also the easiest way to approve something too broad by reflex. Read the proposed pattern. If it is shorter than you expected, narrow it before you accept.&lt;/p&gt;

&lt;h2&gt;
  
  
  Common mistakes
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Forgetting that &lt;code&gt;decision&lt;/code&gt; defaults to &lt;code&gt;allow&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Writing a pattern that is too short, so it covers more than intended.&lt;/li&gt;
&lt;li&gt;Assuming option order does not matter. It does, because the match is an exact prefix.&lt;/li&gt;
&lt;li&gt;Expecting project rules to apply in a repo whose &lt;code&gt;.codex/&lt;/code&gt; layer you have not trusted.&lt;/li&gt;
&lt;li&gt;Relying on rules for security by themselves. They are experimental, and a prefix match is only one layer.&lt;/li&gt;
&lt;li&gt;Assuming Work Cloud setups read local files. The docs say local &lt;code&gt;.rules&lt;/code&gt; files don't apply there; Work Cloud containers follow existing Work Cloud policies, and admins set supported command rules in the &lt;code&gt;rules&lt;/code&gt; TOML field in Agent Security.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Codex rules turn "approve this again" into a decision you make once, in a file you can review and test. Start with a few narrow &lt;code&gt;allow&lt;/code&gt; rules for commands you run constantly, add &lt;code&gt;forbidden&lt;/code&gt; rules with a justification for the commands that should never run, and always run &lt;code&gt;codex execpolicy check&lt;/code&gt; on real command lines before trusting the result. Treat the whole feature as experimental, and keep the sandbox and server-side protections as your backstop.&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-configuration/rules" rel="noopener noreferrer"&gt;Codex rules (OpenAI docs)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://github.com/openai/codex/blob/main/docs/execpolicy.md" rel="noopener noreferrer"&gt;openai/codex execpolicy doc pointer&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/codex-rules-prefix-rule-allow-forbid-commands/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=codex-rules-prefix-rule-allow-forbid-commands" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>codex</category>
      <category>ai</category>
      <category>security</category>
      <category>devops</category>
    </item>
    <item>
      <title>What Is a Staging Environment? A Plain Guide for Founders</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Wed, 11 Nov 2026 08:42:12 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/what-is-a-staging-environment-a-plain-guide-for-founders-4lnn</link>
      <guid>https://dev.to/nixonperinchery/what-is-a-staging-environment-a-plain-guide-for-founders-4lnn</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A staging environment is a nearly exact copy of your live product where a change is tried before real customers can see it.&lt;/li&gt;
&lt;li&gt;It matters more with AI agents, because they produce changes quickly and a mistake on the live product affects real customers.&lt;/li&gt;
&lt;li&gt;Staging only protects you if it matches the live setup closely; a copy that differs gives false comfort.&lt;/li&gt;
&lt;li&gt;Staging cannot easily copy heavy traffic or problems that take a long time to appear, so keep a way back and check the live product right after release.&lt;/li&gt;
&lt;li&gt;Your job at staging is simple: click through the five things that matter most, then decide whether to go live.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A staging environment is a private copy of your live product, set up to match it as closely as possible, where a change is tried before customers see it. If you work with an AI coding agent, it is the place where you check the work with your own eyes, and where mistakes are cheap. Here is what it is, what it can and cannot catch, and what to ask for.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is a staging environment, in plain words?
&lt;/h2&gt;

&lt;p&gt;Think of a restaurant that tests a new dish on the staff before it goes on the menu. The kitchen is the same and the recipe is the same. Only the diners are different. If the dish is bad, nobody paying has been harmed.&lt;/p&gt;

&lt;p&gt;Staging works the same way for software. TechTarget &lt;a href="https://www.techtarget.com/searchsoftwarequality/definition/staging-environment" rel="noopener noreferrer"&gt;defines it&lt;/a&gt; as "a nearly exact replica of a production environment for software testing". "Production" is the word engineers use for the live product, the one your customers use. Because staging is separate, a serious flaw can break staging without taking the live product down.&lt;/p&gt;

&lt;p&gt;There are usually three places a change passes through:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Development:&lt;/strong&gt; where the work is built. It is rough and changes constantly.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Staging:&lt;/strong&gt; the dress rehearsal. It looks and behaves like the real thing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Production:&lt;/strong&gt; the live product, used by real people.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Why does staging matter more with AI coding agents?
&lt;/h2&gt;

&lt;p&gt;An AI agent works fast. It can produce in an afternoon what used to take a team much longer. That is a real benefit, but it also means more changes arrive, and each one is a chance for something to be wrong.&lt;/p&gt;

&lt;p&gt;The agent's own tests tell you the code did what the agent expected. They do not tell you that the sign-up page still works with your real settings, or that the new report looks right to the person who reads it every Monday. Staging is where a human answers those questions.&lt;/p&gt;

&lt;p&gt;It also fits how agents are meant to be used. Anthropic's security page for Claude Code states that &lt;a href="https://code.claude.com/docs/en/security" rel="noopener noreferrer"&gt;you are responsible for reviewing proposed code and commands&lt;/a&gt; for safety before approval. Reviewing is easier when you can click through a working copy instead of reading a description of one.&lt;/p&gt;

&lt;h2&gt;
  
  
  What should staging match?
&lt;/h2&gt;

&lt;p&gt;Staging is only useful if it resembles the live product. TechTarget says everything in staging should be as close a copy of production as possible, including the same hardware, server, database and cache settings. It warns that when the two differ, the data gathered from the tests isn't accurate and defects could be released to production.&lt;/p&gt;

&lt;p&gt;In plain terms, ask three questions:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Is it set up the same way?&lt;/strong&gt; Same kind of server, same settings, same connected services where possible. A rehearsal on a different stage proves little.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Does it have realistic data?&lt;/strong&gt; A page that works with five test customers may crawl or break with fifty thousand. Staging should hold data that looks like yours.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Is it released the same way?&lt;/strong&gt; If staging is put live one way and production another, you have tested the wrong thing.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Realistic data raises a second question: privacy. Copies of real customer data need the same care as the original. Ask who can see staging and whether personal details are hidden or removed.&lt;/p&gt;

&lt;h2&gt;
  
  
  What staging cannot catch
&lt;/h2&gt;

&lt;p&gt;Staging reduces risk. It does not remove it. TechTarget lists some limits worth knowing:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Traffic:&lt;/strong&gt; it can be extremely difficult or impractical to recreate heavy traffic, so a change that only fails under load can slip through.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Mismatch:&lt;/strong&gt; any difference from production can hide a problem.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Slow problems:&lt;/strong&gt; things like memory leaks, where a system gradually uses up its memory, can take longer to show up. Staging needs to run as long as production does to expose them.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;So staging is not a promise that go-live will be smooth. Pair it with two habits. First, make sure there is a marked way back, so you can undo a release quickly. Second, check the live product straight after release, not a week later.&lt;/p&gt;

&lt;h2&gt;
  
  
  What about the database?
&lt;/h2&gt;

&lt;p&gt;Changes to stored data are the riskiest part of any release, because they can be hard to undo. A new field, a renamed column or a clean-up of old records all touch your customers' information.&lt;/p&gt;

&lt;p&gt;The safe pattern is to rehearse those changes on a copy first, and to be sure a backup exists and actually restores before touching the live data.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you check a change on staging?
&lt;/h2&gt;

&lt;p&gt;You do not need to understand the code. You need a short list and ten minutes.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Ask what changed, in one paragraph.&lt;/strong&gt; If the agent or your team cannot say it simply, that is a finding.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Pick the five things that matter most.&lt;/strong&gt; Usually sign-up or sign-in, the main thing customers do, anything involving money, anything that sends messages, and the report or screen you personally rely on.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Click through them as a customer would.&lt;/strong&gt; Use a normal account, not an admin one, as well as an admin one.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Try one thing that should fail.&lt;/strong&gt; Enter a wrong password, an empty form, a letter where a number belongs. Good software refuses politely.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Look at something that did not change.&lt;/strong&gt; Side effects often show up next to the new work, not in it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Write down what you saw.&lt;/strong&gt; "Checkout works with a card, fails with no message when the card is declined" is a useful note. "Looks fine" is not.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If something is off, describe it the way you would to a colleague: what you did, what you expected, what happened.&lt;/p&gt;

&lt;h2&gt;
  
  
  Who decides when to go live?
&lt;/h2&gt;

&lt;p&gt;You do, or someone you name. The step from staging to production is a business decision, not only a technical one. A change that is technically finished may still be wrong to release on a Friday evening, or the week of a big campaign.&lt;/p&gt;

&lt;p&gt;Be wary of any setup where an AI agent can put changes on the live product by itself, with no one signing off. Keep the live product's passwords and access away from the agent's everyday work, so the easy path is always staging first.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does Atlas do about staging?
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=what-is-staging-environment-plain-guide" rel="noopener noreferrer"&gt;Atlas&lt;/a&gt; is a team of AI engineers built on Claude Code. Its releases beyond the Mac follow eight steps: the way back is marked, data is backed up and the backup proven by restoring it, database changes are rehearsed on that copy, then the release goes out and is checked. It has a program that does a plain staging deploy when the release steps can be followed exactly, and another that re-runs the tests a fix named on staging. Production go-lives are never decided for you.&lt;/p&gt;

&lt;p&gt;What Atlas does not do today is give you a plain-English walk-through for the person signing off on staging, covering what changed and what to click. That is coming to Atlas, built in, so it needs no setup on your side. Until then, use the six-step list above before you tell PA to go ahead.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Staging is a cheap place to be wrong. It gives you a safe place to look at AI-built work before customers do. Make sure it matches the live product, use realistic but protected data, and spend ten minutes on the five things that matter. Then keep a way back and check the live product right after release, because staging can reduce risk but never remove it.&lt;/p&gt;

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

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://www.techtarget.com/searchsoftwarequality/definition/staging-environment" rel="noopener noreferrer"&gt;TechTarget: staging environment definition&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/security" rel="noopener noreferrer"&gt;Claude Code security (Anthropic docs)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/what-is-staging-environment-plain-guide/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=what-is-staging-environment-plain-guide" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>founders</category>
      <category>testing</category>
      <category>ai</category>
      <category>devops</category>
    </item>
    <item>
      <title>Claude Code in a Monorepo or Large Codebase: Setup Guide</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Mon, 09 Nov 2026 08:33:20 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/claude-code-in-a-monorepo-or-large-codebase-setup-guide-1e68</link>
      <guid>https://dev.to/nixonperinchery/claude-code-in-a-monorepo-or-large-codebase-setup-guide-1e68</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;In a large repository, keep Claude's context on the part of the code a task touches: unrelated instructions and file reads cost tokens and can degrade Claude's performance.&lt;/li&gt;
&lt;li&gt;Where you launch claude decides which files it can edit without another grant, which CLAUDE.md files load at startup and which project settings apply, so start from the package you are working in when the work is scoped.&lt;/li&gt;
&lt;li&gt;Per-directory CLAUDE.md files, claudeMdExcludes and Read deny rules keep other teams' conventions, generated code and vendored code out of context.&lt;/li&gt;
&lt;li&gt;worktree.sparsePaths with symlinkDirectories makes worktrees lighter, and a code intelligence plugin lets Claude look up definitions and references through a language server instead of scanning files.&lt;/li&gt;
&lt;li&gt;Deny rules do not stop a Bash search such as grep -r from listing denied files, so treat them as a context filter, not a security boundary.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To set up Claude Code in a monorepo or large codebase, scope it to the part of the tree each task touches: start it from the package you are working in, split instructions into per-directory CLAUDE.md files, and block reads of generated and vendored code. The defaults are tuned for smaller projects. In a big tree they can fill the context window with instructions and file reads unrelated to the task, which costs tokens and, according to &lt;a href="https://code.claude.com/docs/en/large-codebases.md" rel="noopener noreferrer"&gt;Anthropic's large-codebase guide&lt;/a&gt;, degrades Claude's performance.&lt;/p&gt;

&lt;p&gt;This article walks through that guide's settings in the order you would apply them, with config you can copy. Each setting is independent, so adopt the ones that fit your repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does a large codebase need different setup?
&lt;/h2&gt;

&lt;p&gt;Instructions and file reads both grow with the size of the repository. A single root CLAUDE.md that covers every subsystem either grows long and mostly irrelevant to any one task, or stays so generic it helps nobody. File searches pull in generated and vendored code that no one wants Claude to read.&lt;/p&gt;

&lt;p&gt;The fix is the same in each case: load less, and load it only when it matters. Everything below is a way to do that.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where should you start Claude Code in a monorepo?
&lt;/h2&gt;

&lt;p&gt;Where you run &lt;code&gt;claude&lt;/code&gt; decides which files it can read and edit without another permission grant, which CLAUDE.md files load at launch, and which project settings apply. The docs give this split:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Start from&lt;/th&gt;
&lt;th&gt;File access&lt;/th&gt;
&lt;th&gt;CLAUDE.md loaded at launch&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Repository root&lt;/td&gt;
&lt;td&gt;Every file&lt;/td&gt;
&lt;td&gt;Root only; subdirectory files load on demand&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;A subdirectory&lt;/td&gt;
&lt;td&gt;That subtree only, until you grant more&lt;/td&gt;
&lt;td&gt;That directory's plus every ancestor's&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Start from the root when a task spans packages. Start from a package when the work stays inside it. One catch: project settings in &lt;code&gt;.claude/settings.json&lt;/code&gt; are not inherited from parent directories the way CLAUDE.md files are. If you launch from &lt;code&gt;packages/api/&lt;/code&gt;, the settings that apply are that directory's, so each subdirectory's settings file has to be self-contained.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you layer CLAUDE.md files by directory?
&lt;/h2&gt;

&lt;p&gt;Keep the root file for rules that apply everywhere, and put area-specific conventions next to the code. Claude Code loads CLAUDE.md files from the working directory and every parent at launch, then loads each subdirectory's file on demand. Commit them so teammates inherit them; the directory's owners usually maintain their file.&lt;/p&gt;

&lt;p&gt;The root file from the docs' example:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;Run package scripts from the package directory, not the monorepo root.
Prefix commit subjects with the package name, for example &lt;span class="sb"&gt;`api: add rate limiting`&lt;/span&gt;.
Never edit files under packages/&lt;span class="err"&gt;*&lt;/span&gt;/generated/. Run &lt;span class="sb"&gt;`npm run codegen`&lt;/span&gt; in the package instead.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And &lt;code&gt;packages/api/CLAUDE.md&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;Copy &lt;span class="sb"&gt;`.env.example`&lt;/span&gt; to &lt;span class="sb"&gt;`.env`&lt;/span&gt; before running anything. Tests and the dev server fail without it.
Write database queries with the Knex query builder. Never put raw SQL strings in route handlers.
Never edit a migration after it has merged. Add a new migration instead.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Started from &lt;code&gt;packages/api/&lt;/code&gt;, Claude sees both files and nothing from &lt;code&gt;packages/web/&lt;/code&gt;. To check what actually loaded, run &lt;code&gt;/context all&lt;/code&gt; and look under &lt;strong&gt;Memory files&lt;/strong&gt;. If a checked-in file has grown too large, the docs point to the &lt;code&gt;/doctor&lt;/code&gt; checkup.&lt;/p&gt;

&lt;p&gt;Three habits keep these files honest, all from the same guide:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Review CLAUDE.md edits in pull requests, like any documentation change.&lt;/li&gt;
&lt;li&gt;Revisit them after major model releases, since a workaround for an older model's limitation can become overhead.&lt;/li&gt;
&lt;li&gt;Consider a &lt;code&gt;Stop&lt;/code&gt; hook. It receives the path to the session transcript when Claude finishes responding, so a script can propose CLAUDE.md updates while the gap is fresh.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  Per-directory CLAUDE.md or path-scoped rules?
&lt;/h3&gt;

&lt;p&gt;Both target instructions at part of the tree. Per-directory files live with the code and are maintained by that directory's owners. Rules under &lt;code&gt;.claude/rules/&lt;/code&gt; live centrally and load when Claude works with a file matching the rule's &lt;code&gt;paths:&lt;/code&gt; glob, which suits conventions that apply to many scattered paths.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you exclude CLAUDE.md files you never need?
&lt;/h2&gt;

&lt;p&gt;When you start from the root, subdirectory files can load on demand. The &lt;code&gt;claudeMdExcludes&lt;/code&gt; setting skips files by glob so they never load. Patterns are matched against absolute file paths, so begin relative-style patterns with &lt;code&gt;**/&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;"claudeMdExcludes"&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;"**/packages/web/**"&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;This skips every CLAUDE.md and rules file under that package. Put it in &lt;code&gt;.claude/settings.local.json&lt;/code&gt; if it is only for you. Claude Code adds that file to your global gitignore when it saves a setting there, but if you create it by hand, add it to gitignore yourself.&lt;/p&gt;

&lt;p&gt;The list is static, not a per-task switch: to work on a different package tomorrow, start Claude from that package instead of editing exclusions. The setting works at any settings scope and arrays merge across scopes. A managed organisation-wide CLAUDE.md cannot be excluded this way.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you stop Claude reading generated and vendored code?
&lt;/h2&gt;

&lt;p&gt;Content searches respect &lt;code&gt;.gitignore&lt;/code&gt; by default, so &lt;code&gt;node_modules/&lt;/code&gt;, &lt;code&gt;dist/&lt;/code&gt; and &lt;code&gt;build/&lt;/code&gt; are usually covered if they are listed there. For checked-in generated code or a vendored SDK, add &lt;code&gt;Read&lt;/code&gt; deny rules:&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;"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="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"Read(./**/dist/**/*)"&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(./**/build/**/*)"&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(./**/*.generated.*)"&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(./**/vendor/**/*)"&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;The patterns end in &lt;code&gt;/**/*&lt;/code&gt;, not &lt;code&gt;/**&lt;/code&gt;, so Claude can still list or &lt;code&gt;cd&lt;/code&gt; into the directories but cannot open what is inside. Commit the rules to &lt;code&gt;.claude/settings.json&lt;/code&gt; for the team, use &lt;code&gt;.claude/settings.local.json&lt;/code&gt; for yourself, or use managed settings to enforce them for everyone. Relative patterns anchor at the session's working directory, so if you start sessions from subdirectories and keep the rules in the root's local file, write them as &lt;code&gt;//&lt;/code&gt;-absolute paths.&lt;/p&gt;

&lt;p&gt;Know the limits. Deny rules cover Claude's built-in file tools. In Bash they cover the file commands Claude Code recognises, such as &lt;code&gt;cat&lt;/code&gt;, &lt;code&gt;head&lt;/code&gt;, &lt;code&gt;grep&lt;/code&gt; and &lt;code&gt;find&lt;/code&gt;, when a denied path appears as an argument. A Bash search like &lt;code&gt;grep -r&lt;/code&gt; or &lt;code&gt;find&lt;/code&gt; over a directory that contains denied files still includes them, and deny rules do not cover subprocesses that open files themselves. Use them to save context, not as a security control.&lt;/p&gt;

&lt;h2&gt;
  
  
  Can Claude find code without scanning every file?
&lt;/h2&gt;

&lt;p&gt;In a large tree, finding a symbol's definition or callers can cost many file reads and grep calls. A code intelligence plugin connects Claude to a language server so it can jump to definitions, find references and surface type errors directly. The &lt;a href="https://code.claude.com/docs/en/common-workflows" rel="noopener noreferrer"&gt;common workflows page&lt;/a&gt; recommends installing one for your language. From the official marketplace, the TypeScript one installs at the &lt;code&gt;claude&lt;/code&gt; prompt with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;/plugin &lt;span class="nb"&gt;install &lt;/span&gt;typescript-lsp@claude-plugins-official
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If Claude Code reports that the marketplace is not found, add it with &lt;code&gt;/plugin marketplace add anthropics/claude-plugins-official&lt;/code&gt; and retry. If it reports the plugin is not found, refresh the catalog with &lt;code&gt;/plugin marketplace update claude-plugins-official&lt;/code&gt;. Each developer's machine also needs the language's server binary. To enable a plugin for everyone in the repository, use the &lt;code&gt;enabledPlugins&lt;/code&gt; project setting.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you keep worktrees light in a big repo?
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://code.claude.com/docs/en/common-workflows" rel="noopener noreferrer"&gt;&lt;code&gt;claude --worktree&lt;/code&gt;&lt;/a&gt; starts a session in its own git worktree, a separate checkout on its own branch. By default it checks out the whole repository. The &lt;code&gt;worktree.sparsePaths&lt;/code&gt; setting uses git sparse-checkout to write only the listed directories plus root-level files. Pair it with &lt;code&gt;symlinkDirectories&lt;/code&gt; so &lt;code&gt;node_modules&lt;/code&gt; is symlinked back to the main copy instead of duplicated:&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;"worktree"&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;"sparsePaths"&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;".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;"packages/api"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="s2"&gt;"packages/shared"&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;"symlinkDirectories"&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;"node_modules"&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;Paths are relative to the repository root, whichever subdirectory you start from. Root-level files such as &lt;code&gt;package.json&lt;/code&gt; and lock files always come along, but root-level directories do not, so list &lt;code&gt;.claude&lt;/code&gt; if you want the root settings or rules inside the worktree. List directories, not individual files.&lt;/p&gt;

&lt;p&gt;This also helps subagents that run in worktrees, since each gets a lightweight checkout. All worktrees in a session share the same &lt;code&gt;sparsePaths&lt;/code&gt;, so list every package any subagent needs. If you set it in &lt;code&gt;.claude/settings.local.json&lt;/code&gt;, the lists merge with the committed one: a local file can add paths but not remove them.&lt;/p&gt;

&lt;p&gt;One gotcha: inside a worktree the working directory is the worktree root, so a package's own &lt;code&gt;.claude/settings.json&lt;/code&gt; does not load there. Put settings you need in worktrees, such as deny rules or hooks, in the repository root's &lt;code&gt;.claude/settings.json&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do you edit across packages?
&lt;/h2&gt;

&lt;p&gt;Started from &lt;code&gt;packages/api/&lt;/code&gt;, Claude can read and edit files in that directory. Grant access to siblings with &lt;code&gt;additionalDirectories&lt;/code&gt; or a flag:&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;"additionalDirectories"&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;"../shared"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"../web"&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;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--add-dir&lt;/span&gt; ../shared
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The two differ in what else loads. Directories from the &lt;code&gt;additionalDirectories&lt;/code&gt; setting never load their CLAUDE.md, rules or skills. With &lt;code&gt;--add-dir&lt;/code&gt; or &lt;code&gt;/add-dir&lt;/code&gt;, skills load, and CLAUDE.md and rules load only if you set an environment variable:&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_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1 claude &lt;span class="nt"&gt;--add-dir&lt;/span&gt; ../shared
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For a change that crosses packages, such as a shared type and its call sites, the guide suggests giving Claude the whole change in one session and planning first in plan mode. Claude writes the plan to a file, and Claude Code re-injects that file after each compaction, so the plan survives a long session.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where do skills and plugins fit?
&lt;/h2&gt;

&lt;p&gt;Skills under a directory's &lt;code&gt;.claude/skills/&lt;/code&gt; load on demand when Claude determines they are relevant. Claude picks a skill by reading every discovered skill's name and description, and only the chosen skill's full content enters context. So area-specific procedures, such as a package's testing patterns, cost little until needed. A skill's &lt;code&gt;paths&lt;/code&gt; frontmatter can also scope it to matching files by glob.&lt;/p&gt;

&lt;p&gt;Keep descriptions short and lead with the words a request would contain, because when there are many skills, some lose their descriptions entirely. Started from the repository root, the skills in scope include those from every subdirectory Claude touches, which can accumulate into the hundreds.&lt;/p&gt;

&lt;p&gt;When per-directory files become hard to govern, the guide recommends moving conventions into skills, versioned plugins owned by a platform team, or an MCP server over a code search or RAG index you already run.&lt;/p&gt;

&lt;h2&gt;
  
  
  A minimal starting point
&lt;/h2&gt;

&lt;p&gt;If you do nothing else, do these four things:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Commit a short root CLAUDE.md and one per package for local conventions.&lt;/li&gt;
&lt;li&gt;Start Claude from the package, not the root, when work is scoped.&lt;/li&gt;
&lt;li&gt;Add &lt;code&gt;Read&lt;/code&gt; deny rules for committed generated and vendored paths.&lt;/li&gt;
&lt;li&gt;Set &lt;code&gt;worktree.sparsePaths&lt;/code&gt; and &lt;code&gt;symlinkDirectories&lt;/code&gt; before running parallel sessions.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Then run &lt;code&gt;/context all&lt;/code&gt; once and confirm only what you expect is loaded.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Atlas does today
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-monorepo-large-codebase-setup" rel="noopener noreferrer"&gt;Atlas&lt;/a&gt; is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session with its own copy of the code to work in, loads only the tools its role uses, and loads the project's instructions once. Atlas also builds and keeps a code map of the project so engineers can find their way around a large codebase. Several engineers at once use your Claude plan's limits faster, so keeping each one's context narrow matters there too.&lt;/p&gt;

&lt;p&gt;Atlas does not yet set up language-server lookups or read blocking for generated and vendored code. That is coming to Atlas, built in, so it will need no setup. Until then, you can apply the deny rules and plugin install above in your own project's settings.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Claude Code does not need a different tool for a large repository, just narrower scoping. Choose the launch directory deliberately, layer instructions by area, keep generated code out of reads, and keep worktrees sparse. Revisit the setup after model releases, because instructions that were once necessary can turn into overhead.&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/large-codebases.md" rel="noopener noreferrer"&gt;Set up Claude Code in a monorepo or large codebase&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/common-workflows" rel="noopener noreferrer"&gt;Common workflows - Claude Code Docs&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/claude-code-monorepo-large-codebase-setup/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-monorepo-large-codebase-setup" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>claudecode</category>
      <category>ai</category>
      <category>monorepo</category>
      <category>productivity</category>
    </item>
    <item>
      <title>Technical Debt in AI-Built Software: A Plain Guide</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Fri, 06 Nov 2026 06:26:17 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/technical-debt-in-ai-built-software-a-plain-guide-1hb9</link>
      <guid>https://dev.to/nixonperinchery/technical-debt-in-ai-built-software-a-plain-guide-1hb9</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Technical debt is the hidden cost of shortcuts in software: it works today, but every later change gets slower and riskier.&lt;/li&gt;
&lt;li&gt;AI coding agents add code quickly, so debt can build up quietly unless someone also asks for tidy-up work, not only new features.&lt;/li&gt;
&lt;li&gt;GitClear's analysis of 211 million changed lines found that in 2024 duplicated code blocks rose eightfold and copy-pasted lines outnumbered moved lines. That is a trend across projects, not proof about any single one.&lt;/li&gt;
&lt;li&gt;You can keep debt low without reading code: give the agent a check it must pass, write down your rules, schedule clean-up tasks, and have the whole project reviewed now and then.&lt;/li&gt;
&lt;li&gt;The warning sign you can see yourself is that small changes take longer or break unrelated things.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Technical debt is the hidden cost of shortcuts in software. The product works today, but each later change takes longer and breaks more. AI coding agents can build up debt quickly because they add code so fast. It pays to know what debt looks like and how to keep it small, even if you never read a line of code.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is technical debt, in plain English?
&lt;/h2&gt;

&lt;p&gt;Think of a kitchen in a busy restaurant. If every cook puts tools back anywhere, service still runs on day one. By month six, nobody can find anything, two cooks make the same sauce twice, and a simple new dish takes a whole afternoon to set up.&lt;/p&gt;

&lt;p&gt;Software works the same way. "Debt" is the name for the mess that builds up when work is done quickly and not tidied. You borrow speed now and pay interest later, in these forms:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;New features take longer than they did at the start.&lt;/li&gt;
&lt;li&gt;A change in one place breaks something in another.&lt;/li&gt;
&lt;li&gt;Fixing one bug brings back an old one.&lt;/li&gt;
&lt;li&gt;Only the original builder, human or AI, seems to know how things fit together.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Debt is not always bad. A founder who ships a rough first version to test an idea is making a sensible loan. The trouble starts when nobody knows the loan exists.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why can AI-built software pile up debt faster?
&lt;/h2&gt;

&lt;p&gt;A coding agent is very good at adding things. Ask for a new screen and you get one, often in minutes. What it may not do on its own is stop and ask whether a similar screen already exists that it could reuse. It builds what you asked for, in the way that is easiest from where it stands.&lt;/p&gt;

&lt;p&gt;Anthropic's guidance for Claude Code makes a related point. Some knowledge about a project cannot be seen from the code alone, and the guidance names examples: a deploy process that lives in someone's head, and a check that has to pass before anything counts as done. The agent cannot follow a rule it has never been shown. A rule such as "we always do payments this way" stays invisible until you write it down.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does the research say?
&lt;/h2&gt;

&lt;p&gt;Be careful with numbers here, and know what they do and do not show. LeadDev, in an article from February 2025, reported on research by GitClear, a company that analyses code. The research looked at 211 million changed lines of code from 2020 to 2024. It found that in 2024:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Blocks of five or more duplicated lines rose eightfold in frequency.&lt;/li&gt;
&lt;li&gt;Copy-pasted lines outnumbered moved lines. Moving code is a sign that people are reusing and tidying, and GitClear treats it as a stand-in for reuse. That kind of movement declined from the year before.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The same article cites Google's 2024 DORA report. It linked a 25% rise in AI use with faster code reviews and better documentation, and also with a 7.2% drop in delivery stability. (DORA is Google's yearly research on how well software teams deliver.)&lt;/p&gt;

&lt;p&gt;These are trends across many projects in a period when AI tools spread. They do not prove that any one project, or any one tool, produced the duplication. Treat them as a reason to check your own project, not as a verdict.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I spot technical debt without reading code?
&lt;/h2&gt;

&lt;p&gt;You can see the effects even if you cannot see the cause. Watch for these signs:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Slowing delivery.&lt;/strong&gt; The first ten features took a day each. The next ten take a week each, and nothing about them is harder.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Surprise breakage.&lt;/strong&gt; A change to the invoice screen breaks the sign-up screen.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Repeat bugs.&lt;/strong&gt; The same kind of fault keeps returning in different places. That can mean the same logic was copied in several places and only some copies were fixed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Rising cost for similar work.&lt;/strong&gt; If a similar task takes noticeably more time or money than it used to, ask why.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Nervous builders.&lt;/strong&gt; If the agent or the team starts calling a change "risky" for no clear reason, ask what makes it so.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Keep a simple note each month: how long did a typical small change take, and how many things broke afterwards? A trend is worth more than any single reading.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I keep debt low when AI builds the software?
&lt;/h2&gt;

&lt;p&gt;You do not need to be technical. You need to ask for the right things.&lt;/p&gt;

&lt;h3&gt;
  
  
  Give the agent a check it must pass
&lt;/h3&gt;

&lt;p&gt;Anthropic's guidance lists "a check that has to pass before anything counts as done" among the things you set up yourself. Automated tests are the usual form: small programs that try the product and fail if something no longer works. When a change breaks something else, the test fails straight away, instead of weeks later when a customer finds it. Without checks, debt hides.&lt;/p&gt;

&lt;h3&gt;
  
  
  Ask for tidy-up work on purpose
&lt;/h3&gt;

&lt;p&gt;Put clean-up on the plan as its own task. After a run of new features, ask for a task that finds repeated logic, merges it into one place, and removes parts nobody uses. Say that the behaviour must not change and that the existing checks must still pass. If you never ask, it rarely happens by itself.&lt;/p&gt;

&lt;h3&gt;
  
  
  Write down your rules
&lt;/h3&gt;

&lt;p&gt;If there is a right way to do things in your product, such as how prices are rounded or how customer data is handled, write it into the instructions the agent is given. This is how a rule in your head becomes a rule the agent can follow.&lt;/p&gt;

&lt;h3&gt;
  
  
  Keep each request small and clear
&lt;/h3&gt;

&lt;p&gt;Large, vague requests tend to produce large, improvised solutions. A clear request with a defined end point leaves the agent less room to invent a new way of doing something your product already does.&lt;/p&gt;

&lt;h3&gt;
  
  
  Have someone look at the whole, not just the change
&lt;/h3&gt;

&lt;p&gt;The LeadDev article says an AI tool has a limited context window, meaning it can only hold so much of the project in view at once. Because of that, it says humans need to review the broader codebase, and it suggests people refactor repeated logic into reusable parts. In practice, that means a periodic review of the whole project by a person, or by a separate reviewer given the whole project. Reviewing one change at a time will not catch debt that builds up across many changes.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is technical debt always a problem?
&lt;/h2&gt;

&lt;p&gt;No. A prototype you will throw away in a month does not need to be tidy. A product you plan to run and extend for years does. The question to ask is how long the code will live. Tell your team or agent which one you are building, so shortcuts are chosen on purpose.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does it cost to ignore it?
&lt;/h2&gt;

&lt;p&gt;Debt costs show up as time and money. Features take longer, so each one costs more, whether that is engineer hours or use of your AI plan. Bugs reach customers more often. In the worst case, a rewrite becomes cheaper than patching, and that is a decision you want to make early, not under pressure.&lt;/p&gt;

&lt;h2&gt;
  
  
  How Atlas fits
&lt;/h2&gt;

&lt;p&gt;Atlas is a team of AI engineers built on Claude Code. Today it keeps a catalogue of build standards for code structure, quality and security, each with its own check of the project's files, and it reviews every build as it finishes. Before a production release, everything going out is reviewed together. That catches some debt early.&lt;/p&gt;

&lt;p&gt;Atlas does not yet show how duplication or tidy-up work trends across a whole project. That view is coming to Atlas, built in, so it needs no setup on your side. Until then, add a clean-up task to your plan after each run of features, and ask for the whole project to be reviewed now and then. You can read more on the &lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=technical-debt-ai-built-software-plain-guide" rel="noopener noreferrer"&gt;Atlas home page&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Technical debt is a cost you can manage, not a mystery. AI agents add code fast, so the tidying has to be planned and not left to chance. Give the agent checks to pass, schedule clean-up, write down your rules, and watch how long small changes take over time. If that time keeps growing, you are paying interest, and it is time to pay some of the loan back.&lt;/p&gt;

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

&lt;ul&gt;
&lt;li&gt;&lt;a href="https://leaddev.com/software-quality/how-ai-generated-code-accelerates-technical-debt" rel="noopener noreferrer"&gt;How AI-generated code accelerates technical debt (LeadDev)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/best-practices" rel="noopener noreferrer"&gt;Best practices for Claude Code (Anthropic)&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/technical-debt-ai-built-software-plain-guide/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=technical-debt-ai-built-software-plain-guide" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>productivity</category>
      <category>beginners</category>
      <category>softwaredevelopment</category>
    </item>
    <item>
      <title>Claude Code Model Config: Aliases, opusplan and Effort</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Wed, 04 Nov 2026 09:46:34 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/claude-code-model-config-aliases-opusplan-and-effort-mlc</link>
      <guid>https://dev.to/nixonperinchery/claude-code-model-config-aliases-opusplan-and-effort-mlc</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Code picks its model from a fixed order: /model in the session beats --model, which beats ANTHROPIC_MODEL, which beats the model key in settings.&lt;/li&gt;
&lt;li&gt;opusplan plans with Opus and executes with Sonnet, so the strongest model is used only for planning.&lt;/li&gt;
&lt;li&gt;Effort is a separate dial from the model, and the CLAUDE_CODE_EFFORT_LEVEL environment variable overrides every other way of setting it.&lt;/li&gt;
&lt;li&gt;Use full model names or the ANTHROPIC_DEFAULT_*_MODEL variables when a pipeline needs a pinned version, because aliases move to the latest release.&lt;/li&gt;
&lt;li&gt;Managed settings can allow-list or deny models, and a fallback chain of up to three models covers overload but not rate limits.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To change the model in Claude Code, type &lt;code&gt;/model &amp;lt;alias&amp;gt;&lt;/code&gt; in a session, start it with &lt;code&gt;claude --model &amp;lt;alias&amp;gt;&lt;/code&gt;, or set &lt;code&gt;"model"&lt;/code&gt; in a settings file. A reasonable setup for many teams is a cheaper default for daily work, &lt;code&gt;opusplan&lt;/code&gt; for bigger changes, and a separate effort level that you raise only for hard tasks. This article covers the aliases, the order in which settings win, effort, subagent models, fallbacks and how to lock models down for a team.&lt;/p&gt;

&lt;p&gt;Everything below comes from the Claude Code model configuration and subagent documentation. Version numbers are given where the docs state a minimum.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which model aliases does Claude Code have?
&lt;/h2&gt;

&lt;p&gt;An alias is a short name that resolves to the newest model of that family. You can use it anywhere a model name is accepted.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Alias&lt;/th&gt;
&lt;th&gt;What it does&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;default&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Clears any override and returns to the default for your account&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;best&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Same model as &lt;code&gt;fable&lt;/code&gt; where Fable is available, otherwise the same as &lt;code&gt;opus&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;fable&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Fable, for the hardest and longest-running tasks&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;opus&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Latest Opus, for complex reasoning&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;sonnet&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Latest Sonnet, for daily coding&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;haiku&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Fast, efficient Haiku, for simple tasks&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;sonnet[1m]&lt;/code&gt;, &lt;code&gt;opus[1m]&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;The same models with a 1M-token context window; no effect where the model already has 1M natively&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;opusplan&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Opus in plan mode, then Sonnet for execution&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;What an alias points to depends on your provider. On the Anthropic API, &lt;code&gt;opus&lt;/code&gt; is Opus 5.5, &lt;code&gt;sonnet&lt;/code&gt; is Sonnet 5.5 and &lt;code&gt;haiku&lt;/code&gt; is Haiku 5.5. On Amazon Bedrock and Google Cloud's Agent Platform, &lt;code&gt;opus&lt;/code&gt; is Opus 5.5 but &lt;code&gt;sonnet&lt;/code&gt; and &lt;code&gt;haiku&lt;/code&gt; resolve to 4.5 versions. On Microsoft Foundry, &lt;code&gt;opus&lt;/code&gt; is Opus 4.6 and &lt;code&gt;sonnet&lt;/code&gt; and &lt;code&gt;haiku&lt;/code&gt; are 4.5 versions. If you run a mixed estate, check what each alias means on each provider before you write a runbook.&lt;/p&gt;

&lt;p&gt;The docs list minimum Claude Code versions for the newest models: v2.1.280 for Opus 5.5, v2.1.284 for Sonnet 5.5, v2.1.293 for Haiku 5.5 and v2.1.257 for Fable 5.1. &lt;code&gt;claude update&lt;/code&gt; upgrades an old install.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I set the model, and which setting wins?
&lt;/h2&gt;

&lt;p&gt;There are five places, listed from highest priority to lowest:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;In a session: &lt;code&gt;/model &amp;lt;alias|name&amp;gt;&lt;/code&gt;, or &lt;code&gt;/model&lt;/code&gt; alone for the picker.&lt;/li&gt;
&lt;li&gt;At startup: &lt;code&gt;claude --model &amp;lt;alias|name&amp;gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The environment variable &lt;code&gt;ANTHROPIC_MODEL&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The &lt;code&gt;model&lt;/code&gt; field in a settings file.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;ANTHROPIC_DEFAULT_MODEL&lt;/code&gt;, which only sets the default for new sessions.
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--model&lt;/span&gt; opus
&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;/model sonnet
&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;"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;"allow"&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;"Bash(npm run lint)"&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;"model"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"opus"&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;Two details catch people out. In the picker, &lt;code&gt;Enter&lt;/code&gt; switches and saves your choice as the &lt;code&gt;model&lt;/code&gt; field in your user settings, while &lt;code&gt;s&lt;/code&gt; switches for this session only. Typing &lt;code&gt;/model &amp;lt;name&amp;gt;&lt;/code&gt; directly behaves like &lt;code&gt;Enter&lt;/code&gt;. And in non-interactive mode (&lt;code&gt;-p&lt;/code&gt;), &lt;code&gt;/model&lt;/code&gt; applies to the current session only and is never saved (v2.1.205 or later).&lt;/p&gt;

&lt;p&gt;&lt;code&gt;ANTHROPIC_DEFAULT_MODEL&lt;/code&gt; (v2.1.236 or later) is the weakest. A new session uses it only when &lt;code&gt;--model&lt;/code&gt;, &lt;code&gt;ANTHROPIC_MODEL&lt;/code&gt;, any &lt;code&gt;model&lt;/code&gt; value in a settings file (including a saved &lt;code&gt;/model&lt;/code&gt; choice) and any organization default are all absent. It is ignored if set to &lt;code&gt;default&lt;/code&gt;, &lt;code&gt;inherit&lt;/code&gt;, &lt;code&gt;opusplan&lt;/code&gt; or &lt;code&gt;haiku&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Resumed sessions (&lt;code&gt;--resume&lt;/code&gt;, &lt;code&gt;--continue&lt;/code&gt;, &lt;code&gt;/resume&lt;/code&gt;) restore the model saved in the transcript, except on Bedrock, Agent Platform and Foundry, where it is not restored. The &lt;code&gt;--model&lt;/code&gt; flag and &lt;code&gt;ANTHROPIC_MODEL&lt;/code&gt; override the restored model.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is opusplan and when should I use it?
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;opusplan&lt;/code&gt; is a hybrid alias. Plan mode runs on &lt;code&gt;opus&lt;/code&gt;, and when you approve the plan and execution starts, Claude Code switches to &lt;code&gt;sonnet&lt;/code&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 &lt;span class="nt"&gt;--model&lt;/span&gt; opusplan
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The reasoning is cost. Choosing an approach, finding the files and spotting risks is where a stronger model earns its price. Applying a plan that is already written is often fine on Sonnet. If you already use plan mode, &lt;code&gt;opusplan&lt;/code&gt; makes the model split automatic.&lt;/p&gt;

&lt;p&gt;Both phases use the context window of their alias. &lt;code&gt;/model opusplan[1m]&lt;/code&gt; asks for the 1M window on both phases where they do not already have it; it needs v2.1.265 or later, and on earlier versions you use &lt;code&gt;--model&lt;/code&gt; or the &lt;code&gt;model&lt;/code&gt; setting. If your admin has restricted models with &lt;code&gt;availableModels&lt;/code&gt; and the newest Opus is excluded but an older one is allowed, planning uses the newest permitted Opus.&lt;/p&gt;

&lt;h2&gt;
  
  
  How does effort work, and how is it different from the model?
&lt;/h2&gt;

&lt;p&gt;Effort is a separate dial that controls how much the model reasons before it acts. The levels are &lt;code&gt;low&lt;/code&gt;, &lt;code&gt;medium&lt;/code&gt;, &lt;code&gt;high&lt;/code&gt;, &lt;code&gt;xhigh&lt;/code&gt; and &lt;code&gt;max&lt;/code&gt; on Fable 5.1, Fable 5, Opus 5.5, Sonnet 5.5, Haiku 5.5, Opus 5, Sonnet 5, Opus 4.8 and Opus 4.7. Opus 4.6 and Sonnet 4.6 have no &lt;code&gt;xhigh&lt;/code&gt;. If a level is not supported, Claude Code uses the highest supported level at or below it, so &lt;code&gt;xhigh&lt;/code&gt; runs as &lt;code&gt;high&lt;/code&gt; on Opus 4.6. Models not in those lists do not support effort.&lt;/p&gt;

&lt;p&gt;Defaults: &lt;code&gt;high&lt;/code&gt; on effort-capable models, except Opus 5.5, Sonnet 5.5 and Haiku 5.5, which start at &lt;code&gt;medium&lt;/code&gt;, and Opus 4.7, which starts at &lt;code&gt;xhigh&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The resolution order, first match wins:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The &lt;code&gt;CLAUDE_CODE_EFFORT_LEVEL&lt;/code&gt; environment variable&lt;/li&gt;
&lt;li&gt;A level picked in the session (&lt;code&gt;/effort&lt;/code&gt;, the &lt;code&gt;/model&lt;/code&gt; picker)&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;--effort&lt;/code&gt; at launch&lt;/li&gt;
&lt;li&gt;Settings: a saved per-model level or the &lt;code&gt;effortLevel&lt;/code&gt; key&lt;/li&gt;
&lt;li&gt;The model's default
&lt;/li&gt;
&lt;/ol&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--effort&lt;/span&gt; xhigh
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;CLAUDE_CODE_EFFORT_LEVEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;auto   &lt;span class="c"&gt;# send no effort level (unset also works)&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;/effort            # interactive slider
/effort high       # set directly
/effort auto       # clear the saved level for the active model
/effort status     # show the current level
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;max&lt;/code&gt; is accepted by the environment variable and &lt;code&gt;/effort&lt;/code&gt; but not by the &lt;code&gt;effortLevel&lt;/code&gt; settings key, which takes only &lt;code&gt;low&lt;/code&gt;, &lt;code&gt;medium&lt;/code&gt;, &lt;code&gt;high&lt;/code&gt; or &lt;code&gt;xhigh&lt;/code&gt;. &lt;code&gt;max&lt;/code&gt; applies to the current session unless you set it through the environment variable. A top-level &lt;code&gt;effortLevel&lt;/code&gt; in user settings does not apply to Opus 5.5, although it does in project, local and managed settings. Skill and subagent frontmatter can also set &lt;code&gt;effort&lt;/code&gt;, which applies while that skill or subagent runs; the environment variable still takes precedence over it.&lt;/p&gt;

&lt;p&gt;A practical pattern: leave the default alone, raise effort for the one task that needs it, then drop back with &lt;code&gt;/effort auto&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which model do subagents use?
&lt;/h2&gt;

&lt;p&gt;Subagents that inherit the main conversation's model follow the session's model at the time they start, so a &lt;code&gt;/model&lt;/code&gt; switch reaches them. Switch to Opus before delegating and they run on Opus.&lt;/p&gt;

&lt;p&gt;To keep a helper cheap, set &lt;code&gt;model&lt;/code&gt; in its definition. It accepts &lt;code&gt;sonnet&lt;/code&gt;, &lt;code&gt;opus&lt;/code&gt;, &lt;code&gt;haiku&lt;/code&gt;, &lt;code&gt;fable&lt;/code&gt;, a full ID such as &lt;code&gt;claude-opus-5-5&lt;/code&gt;, or &lt;code&gt;inherit&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight yaml"&gt;&lt;code&gt;&lt;span class="nn"&gt;---&lt;/span&gt;
&lt;span class="na"&gt;name&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;code-reviewer&lt;/span&gt;
&lt;span class="na"&gt;description&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;Reviews code for quality and best practices&lt;/span&gt;
&lt;span class="na"&gt;model&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s"&gt;haiku&lt;/span&gt;
&lt;span class="nn"&gt;---&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Since v2.1.251 a subagent's model is resolved in this order:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;The &lt;code&gt;model&lt;/code&gt; parameter on the Agent tool call (aliases only)&lt;/li&gt;
&lt;li&gt;The &lt;code&gt;model&lt;/code&gt; in the subagent's definition&lt;/li&gt;
&lt;li&gt;The &lt;code&gt;CLAUDE_CODE_SUBAGENT_MODEL&lt;/code&gt; environment variable&lt;/li&gt;
&lt;li&gt;The main conversation's model&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Setting &lt;code&gt;CLAUDE_CODE_SUBAGENT_MODEL&lt;/code&gt; alone does not change the built-in Explore and Plan subagents. To force one model onto every subagent, also set &lt;code&gt;CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1&lt;/code&gt; (v2.1.257 or later). While it is on, the &lt;code&gt;model&lt;/code&gt; field in definitions is ignored and Claude cannot pass a model when starting a subagent:&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;"env"&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_CODE_SUBAGENT_MODEL"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"haiku"&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_CODE_SUBAGENT_MODEL_FORCE"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"1"&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;Run &lt;code&gt;/tasks&lt;/code&gt; while a subagent is running to see the model, and its effort level if set, on its row (v2.1.242 or later).&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I pin a model version for CI or a team?
&lt;/h2&gt;

&lt;p&gt;Aliases move. When a newer Sonnet replaces Sonnet 5.5, &lt;code&gt;sonnet&lt;/code&gt; follows. For a pipeline that must behave the same next month, pin one of two ways: use the full model name (for example &lt;code&gt;claude-opus-5-5&lt;/code&gt;), or set the matching variable so the alias keeps meaning what you chose:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;&lt;code&gt;ANTHROPIC_DEFAULT_OPUS_MODEL&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ANTHROPIC_DEFAULT_SONNET_MODEL&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ANTHROPIC_DEFAULT_HAIKU_MODEL&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;ANTHROPIC_DEFAULT_FABLE_MODEL&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Pinning has a cost: you also have to notice when a pinned model is retired and move on purpose.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I restrict which models people can use?
&lt;/h2&gt;

&lt;p&gt;In managed settings, &lt;code&gt;availableModels&lt;/code&gt; is an allow-list. Entries can be a family (&lt;code&gt;sonnet&lt;/code&gt;), a version prefix (&lt;code&gt;claude-sonnet-4-5&lt;/code&gt;) or a full ID. A prefix also matches later IDs that extend it, so &lt;code&gt;claude-fable-5&lt;/code&gt; permits Fable 5 and 5.1.&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;"availableModels"&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;"sonnet"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"haiku"&lt;/span&gt;&lt;span class="p"&gt;],&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"enforceAvailableModels"&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;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ul&gt;
&lt;li&gt;The list applies everywhere a user can name a model: &lt;code&gt;/model&lt;/code&gt;, &lt;code&gt;--model&lt;/code&gt;, &lt;code&gt;ANTHROPIC_MODEL&lt;/code&gt;, the &lt;code&gt;model&lt;/code&gt; setting, the model restored on resume, subagent and teammate models, skill and command models, and &lt;code&gt;/fast&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A blocked &lt;code&gt;/model&lt;/code&gt; choice is rejected. A blocked &lt;code&gt;--model&lt;/code&gt;, &lt;code&gt;ANTHROPIC_MODEL&lt;/code&gt; or &lt;code&gt;model&lt;/code&gt; value is replaced at startup with a warning, and a blocked subagent runs on a fallback model.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;enforceAvailableModels&lt;/code&gt; (v2.1.175 or later) applies the list to the Default option too. Without it, the &lt;code&gt;model&lt;/code&gt; setting is only an initial selection and users can still pick Default in &lt;code&gt;/model&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;deniedModels&lt;/code&gt; (v2.1.283 or later) blocks listed models even if &lt;code&gt;availableModels&lt;/code&gt; permits them, and &lt;code&gt;availableModelsMatch: "exact"&lt;/code&gt; makes each ID permit only the version it names. Both are read from managed settings only; set elsewhere, they are ignored with a warning.&lt;/li&gt;
&lt;li&gt;In managed settings, the &lt;code&gt;availableModels&lt;/code&gt; list applies alone; user, project and local entries cannot extend it. Earlier versions ignore the newer keys, so also set &lt;code&gt;requiredMinimumVersion&lt;/code&gt; to keep them from starting.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What happens when the model is overloaded?
&lt;/h2&gt;

&lt;p&gt;You can give Claude Code a fallback chain:&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;--fallback-model&lt;/span&gt; sonnet,haiku
&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;"fallbackModel"&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-sonnet-5"&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-haiku-4-5"&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;The flag overrides the setting, and chains are capped at three models after duplicates are removed. Fallback triggers on overloaded, unavailable or non-retryable server errors. It does not trigger on authentication, billing, rate-limit, request-size or transport errors, so it will not rescue you when you hit a plan limit. The switch lasts for the current turn only, entries outside &lt;code&gt;availableModels&lt;/code&gt; are dropped, and fallback applies to subagents from v2.1.247. Because a fallback model may differ from the one you chose, look at the model in use when a run behaves oddly.&lt;/p&gt;

&lt;h2&gt;
  
  
  Other variables worth knowing
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;CLAUDE_CODE_DISABLE_1M_CONTEXT=1&lt;/code&gt; removes the &lt;code&gt;[1m]&lt;/code&gt; variants from the picker and treats models with a 1M default as 200K.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;MAX_THINKING_TOKENS=0&lt;/code&gt; turns thinking off on the Anthropic API, except on Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models, where it cannot be turned off.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;CLAUDE_CODE_AUTO_COMPACT_WINDOW&lt;/code&gt; sets the auto-compact window in tokens, such as &lt;code&gt;200000&lt;/code&gt;, and takes precedence over &lt;code&gt;/autocompact&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  A sensible starting setup
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Set &lt;code&gt;"model": "sonnet"&lt;/code&gt; in user settings for daily work.&lt;/li&gt;
&lt;li&gt;Use &lt;code&gt;/model opusplan&lt;/code&gt; before a large, unclear change.&lt;/li&gt;
&lt;li&gt;Keep effort at the default and use &lt;code&gt;/effort&lt;/code&gt; for one hard task, then &lt;code&gt;/effort auto&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;In CI, pin with a full model name and set &lt;code&gt;CLAUDE_CODE_EFFORT_LEVEL&lt;/code&gt; explicitly.&lt;/li&gt;
&lt;li&gt;For a team, publish &lt;code&gt;availableModels&lt;/code&gt; and &lt;code&gt;enforceAvailableModels&lt;/code&gt; in managed settings, with a &lt;code&gt;requiredMinimumVersion&lt;/code&gt;.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Model choice in Claude Code is a stack of settings: the session beats the flag, which beats the environment, which beats the file. Learn that order and the effort order, pin versions where repeatability matters, and let &lt;code&gt;opusplan&lt;/code&gt; spend the stronger model on planning. Most surprises come from one layer silently overriding another, so check &lt;code&gt;/effort status&lt;/code&gt; and the picker before you blame the model.&lt;/p&gt;

&lt;p&gt;Atlas, a team of AI engineers built on Claude Code, gives each engineer its own session with a model and effort suited to its role. Fallback chains are coming to Atlas, built in, so they will need no setup. Until then, set one yourself in Claude Code as shown above.&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;Claude Code model configuration&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/sub-agents" rel="noopener noreferrer"&gt;Claude Code subagents&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/claude-code-model-aliases-opusplan-effort/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-model-aliases-opusplan-effort" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>claudecode</category>
      <category>ai</category>
      <category>productivity</category>
      <category>llm</category>
    </item>
    <item>
      <title>Why AI-Built Work Comes Back for Rework, and How to Cut It</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Mon, 02 Nov 2026 10:59:45 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/why-ai-built-work-comes-back-for-rework-and-how-to-cut-it-340i</link>
      <guid>https://dev.to/nixonperinchery/why-ai-built-work-comes-back-for-rework-and-how-to-cut-it-340i</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Rework is normal with AI coding agents, and most of it comes from a few repeatable causes rather than bad luck.&lt;/li&gt;
&lt;li&gt;The biggest cause is missing information: the agent cannot see decisions, rules and wishes that live only in your head.&lt;/li&gt;
&lt;li&gt;Give the agent a check it can run, such as a test or a screenshot to match, so it can catch its own mistakes before you see them.&lt;/li&gt;
&lt;li&gt;Changing your mind after building has started is the most expensive kind of rework, so settle open questions first.&lt;/li&gt;
&lt;li&gt;Keep rules that must always apply in writing in the project's instruction file, because long chats lose early instructions.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If your AI coding agent keeps coming back with fixes, or redoes things it already called finished, that is common and usually explainable. Rework with AI agents mostly comes from missing information, no way for the agent to check its own work, and requests that change halfway through. You can reduce all three without writing any code.&lt;/p&gt;

&lt;p&gt;This guide explains where rework comes from, which kinds are cheap and which are costly, and what you can do about each.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does "rework" mean with an AI coding agent?
&lt;/h2&gt;

&lt;p&gt;Rework is any work done a second time. The agent builds a feature, someone finds a problem, and the agent goes back to fix it. Or a test fails after the work was called finished. Or you look at the result and say, "That is not what I meant."&lt;/p&gt;

&lt;p&gt;Human teams have rework too. The difference is that an AI agent redoes work quickly, so it can feel free. It is not. Every second pass takes time, and it also uses part of your plan's usage allowance or, on a pay-as-you-go setup, your money.&lt;/p&gt;

&lt;p&gt;Some rework is healthy. A reviewer catching a real flaw before release is the system working. The goal is not zero rework. The goal is to stop paying twice for problems you could have prevented.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why does the agent get it wrong in the first place?
&lt;/h2&gt;

&lt;p&gt;Claude Code's best-practices documentation says that when a session does not go the way you expected, it is almost always because Claude built something different from what you had in mind, or because it is missing information it cannot get from reading the project. Think of a very capable new contractor on day one. They can read everything in the building, but they cannot read your mind.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cause 1: facts that live only in your head
&lt;/h3&gt;

&lt;p&gt;The agent can read your project files. It cannot see a deal you made with a customer last week, a rule your legal team insists on, or the fact that "active user" means something specific at your company. The same documentation lists examples of things no default setting can know: a deploy process that lives in someone's head, a file that must never be read, a check that has to pass before anything counts as done, a budget you need to stay under.&lt;/p&gt;

&lt;p&gt;If you do not say it, the agent guesses. A guess that turns out wrong becomes rework.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cause 2: vague wishes
&lt;/h3&gt;

&lt;p&gt;"Make the signup page better" can mean twenty different things. The agent picks one. You wanted another. Both of you did your job, and the work is still wasted.&lt;/p&gt;

&lt;p&gt;A good brief names the result you want, who it is for, and what must not change. If you can describe how you would test it ("a new visitor can sign up in under a minute, and the welcome email arrives"), the agent can aim at it.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cause 3: the agent has no way to check itself
&lt;/h3&gt;

&lt;p&gt;Anthropic describes Claude Code as working in a loop of three phases: it gathers context, takes action, and verifies the result. Verification is the step that catches mistakes early. It might run the project's tests, read the output, or compare the result with what you asked for.&lt;/p&gt;

&lt;p&gt;The best-practices page says the same thing from the other side: give the agent a check to run. It lists a test file, a build that must succeed, a script that compares output with an expected result, or a screenshot compared against a design mockup. If there are no tests and no clear definition of "correct", the agent can only say, "It looks right to me." Then you or a reviewer find the problem later, when fixing it costs more.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cause 4: long sessions and forgotten instructions
&lt;/h3&gt;

&lt;p&gt;An agent holds the conversation in a limited working space, called the context window. As it fills up, Claude Code shrinks the conversation into a summary. The documentation says that summary keeps your requests and key code, but detailed instructions from early in the conversation may be lost. So a rule you gave at the start of a long session can quietly vanish.&lt;/p&gt;

&lt;p&gt;The fix the documentation gives is to put rules that must always apply in a file called CLAUDE.md, which Claude Code reads at the start of every session, instead of relying on the chat.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cause 5: you changed your mind
&lt;/h3&gt;

&lt;p&gt;This is the costly one, and it is not the agent's fault. If a screen is designed, built and tested, and you then say "actually, we need approvals before it is submitted", parts of finished work must be redone, along with their tests. Nobody did anything wrong. The decision simply arrived late.&lt;/p&gt;

&lt;h2&gt;
  
  
  Which rework is cheap, and which is expensive?
&lt;/h2&gt;

&lt;p&gt;A rough guide:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Cheap:&lt;/strong&gt; a typo, a wording choice or a colour, caught while the work is still open.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Moderate:&lt;/strong&gt; a bug found by a test or a reviewer before release. The agent still has the context and the fix is local.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Expensive:&lt;/strong&gt; a misunderstanding found after several pieces were built on top of it, or a changed requirement after design, building and testing are done.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Very expensive:&lt;/strong&gt; a problem found by customers after release. Some actions cannot be undone by the agent at all. Claude Code can rewind its file edits, but its documentation says that actions affecting remote systems such as databases, APIs and deployments cannot be undone that way.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The pattern is simple: the later a problem is found, the more it costs. Most of the habits below move discovery earlier.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I reduce rework?
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Settle the open questions before building
&lt;/h3&gt;

&lt;p&gt;Spend ten minutes listing what is undecided: who can see this, what happens when it fails, what happens with an empty list, what it must not break. Answer what you can. For what you cannot, say so, and ask the agent to list its assumptions before it starts. Wrong assumptions are far cheaper to fix on paper than in finished work.&lt;/p&gt;

&lt;h3&gt;
  
  
  Describe "done" in your own words
&lt;/h3&gt;

&lt;p&gt;Write two or three sentences about what you would check to accept the work. For example: "I can add a customer, edit their address, and the old address shows in the history." You do not need technical language. This gives the agent the check it needs to tell whether it has succeeded.&lt;/p&gt;

&lt;h3&gt;
  
  
  Ask for tests first on anything that matters
&lt;/h3&gt;

&lt;p&gt;For billing, sign-in, or anything where mistakes are expensive, ask that the tests be written before the feature. A test is a small program that checks the feature works. Then "done" is not an opinion; it is a set of checks that pass.&lt;/p&gt;

&lt;h3&gt;
  
  
  Review in small pieces
&lt;/h3&gt;

&lt;p&gt;One review of a huge batch finds many problems at once, and every fix touches work built on top. Smaller pieces mean smaller fixes. If you see the agent heading the wrong way, you can stop it. Claude Code lets you interrupt at any point and steer it without starting over, so a correction after five minutes beats a correction after five hours.&lt;/p&gt;

&lt;h3&gt;
  
  
  Keep the standing rules in writing
&lt;/h3&gt;

&lt;p&gt;Put the rules that never change (naming, security rules, what the product must never do) into the project's instruction file so they do not depend on a long chat. A fresh session then starts with the same rules as the last one.&lt;/p&gt;

&lt;h3&gt;
  
  
  Notice repeats
&lt;/h3&gt;

&lt;p&gt;If the same kind of problem comes back again and again, such as missing permission checks or unchecked input, add that rule to the standing instructions instead of fixing it each time.&lt;/p&gt;

&lt;h2&gt;
  
  
  How can I tell whether rework is a problem on my project?
&lt;/h2&gt;

&lt;p&gt;Measure it. Ask your team or your tool a few plain questions each week:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;What share of tasks were redoing earlier work?&lt;/li&gt;
&lt;li&gt;What did that cost in time and usage?&lt;/li&gt;
&lt;li&gt;What were the main reasons: unclear request, failed tests, review findings, changed requirements?&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;A share that is steady and small is fine. A share that climbs usually points to the brief, not the tool. If most rework is "changed requirements", the fix is on your side: decide earlier. If it is "failed tests", the fix is better checks or smaller pieces.&lt;/p&gt;

&lt;h2&gt;
  
  
  How Atlas handles rework
&lt;/h2&gt;

&lt;p&gt;Atlas is a team of AI engineers built on Claude Code. You talk to one of them, PA, your project assistant, and PA shares the work out to specialists. Several parts of that are aimed at catching problems early:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Order of work.&lt;/strong&gt; Building waits for an approved architecture, a signed-off design and failing tests, and a screen waits for the API it calls. Questions get settled before code is written.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;"Done" is enforced.&lt;/strong&gt; Completion is refused until the work is on the main branch or queued to land, a screen has its test cases and screenshots, and the product's rules pass.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Review.&lt;/strong&gt; Every build is reviewed as it finishes. It comes back releasable, or fix tasks are filed to the engineer who built it, by name. Before a production release, everything going out is reviewed together.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Lessons carry forward.&lt;/strong&gt; Lessons from finished work are passed to future engineers. One is held back as a control, and lessons that track worse results or higher cost are retired automatically.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Decisions stay with you.&lt;/strong&gt; Atlas never drops scope, spends money or releases to production without you.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Atlas does not yet report the share of work that was redone, with its cost and causes. It also does not yet tell you, at the moment you change a request, how much finished work that change will reopen. Both are coming to Atlas, built in, so they will need no setup on your side. Until then, ask PA what a change would touch before you confirm it, and keep your own weekly tally using the three questions above. Learn more at &lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=why-ai-built-work-needs-rework-how-to-cut-it" rel="noopener noreferrer"&gt;Atlas&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Rework with AI agents is not a sign that the tool is broken. It shows where information was missing, where checks were weak, or where decisions came late. Tell the agent what only you know, define "done" in plain words, settle open questions before building, review in small pieces, and watch the share of redone work each week. Those habits remove most of the avoidable rework.&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/how-claude-code-works" rel="noopener noreferrer"&gt;How Claude Code works&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/best-practices" rel="noopener noreferrer"&gt;Best practices for Claude Code&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/why-ai-built-work-needs-rework-how-to-cut-it/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=why-ai-built-work-needs-rework-how-to-cut-it" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>productivity</category>
      <category>beginners</category>
      <category>softwaredevelopment</category>
    </item>
    <item>
      <title>Claude Code Status Line: Show Context, Cost and Limits</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Wed, 28 Oct 2026 13:02:03 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/claude-code-status-line-show-context-cost-and-limits-1g9k</link>
      <guid>https://dev.to/nixonperinchery/claude-code-status-line-show-context-cost-and-limits-1g9k</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;A Claude Code status line is a script you configure. It receives session data as JSON on stdin and prints a row above the footer. The docs say it runs locally and does not consume API tokens.&lt;/li&gt;
&lt;li&gt;Set it up with the /statusline command, or add a statusLine entry with type command to settings.json.&lt;/li&gt;
&lt;li&gt;The JSON includes context-window percentage, estimated session cost, 5-hour and 7-day plan usage (Pro and Max only) and prompt cache health (v2.1.251 or later).&lt;/li&gt;
&lt;li&gt;Guard every optional field, keep the script fast, and cache slow git calls by session_id. A non-zero exit or empty output blanks the line.&lt;/li&gt;
&lt;li&gt;Session cost is a client-side estimate at list price. On Pro and Max it is not relevant for billing, so use it as a guide.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A Claude Code status line is a row in the terminal that runs a script you choose and shows whatever the script prints. Claude Code passes the script session data as JSON, so you can keep context fill, session cost, plan limits and git state in view without typing a command. Per the docs, it runs locally and does not consume API tokens.&lt;/p&gt;

&lt;p&gt;This guide covers setup, the fields worth showing, a working script, and the mistakes that leave the line blank or stale. It is based on the official status line and cost documentation.&lt;/p&gt;

&lt;h2&gt;
  
  
  What is the Claude Code status line?
&lt;/h2&gt;

&lt;p&gt;The status line renders in its own row above the built-in footer badges. It does not replace them, but once a custom status line is configured, Claude Code stops showing most of the footer's keyboard hints, including &lt;code&gt;esc to interrupt&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Your script reads JSON on stdin and writes text to stdout. Each line you print becomes a row. You can use ANSI colors, and OSC 8 escape sequences for clickable links in terminals that support them (iTerm2, Kitty, WezTerm).&lt;/p&gt;

&lt;p&gt;Three reasons to use one:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Context fill.&lt;/strong&gt; You see how full the window is before a compaction fires.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Which session is which.&lt;/strong&gt; With several sessions open, the line can show the branch, worktree or session name.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Limits and spend.&lt;/strong&gt; Plan usage and cost sit next to your prompt instead of behind a command.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  How do I set up a status line?
&lt;/h2&gt;

&lt;p&gt;There are two routes.&lt;/p&gt;

&lt;h3&gt;
  
  
  Option 1: let Claude write it
&lt;/h3&gt;

&lt;p&gt;Run &lt;code&gt;/statusline&lt;/code&gt; with a plain-language request. Claude Code generates a script in &lt;code&gt;~/.claude/&lt;/code&gt; and updates your settings:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;/statusline show model name and context percentage with a progress bar
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Approve the file edit prompts if Claude Code asks for permission.&lt;/p&gt;

&lt;h3&gt;
  
  
  Option 2: configure it by hand
&lt;/h3&gt;

&lt;p&gt;Add a &lt;code&gt;statusLine&lt;/code&gt; field to &lt;code&gt;~/.claude/settings.json&lt;/code&gt; (user settings) or to project settings. Set &lt;code&gt;type&lt;/code&gt; to &lt;code&gt;"command"&lt;/code&gt; and point &lt;code&gt;command&lt;/code&gt; at a script:&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;"statusLine"&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;"~/.claude/statusline.sh"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"padding"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="mi"&gt;2&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;The &lt;code&gt;command&lt;/code&gt; runs in a shell, so an inline command works too. This one uses &lt;code&gt;jq&lt;/code&gt; to print the model and context percentage:&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;"statusLine"&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;"jq -r '&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&gt;[&lt;/span&gt;&lt;span class="se"&gt;\\&lt;/span&gt;&lt;span class="s2"&gt;(.model.display_name)] &lt;/span&gt;&lt;span class="se"&gt;\\&lt;/span&gt;&lt;span class="s2"&gt;(.context_window.used_percentage // 0)% context&lt;/span&gt;&lt;span class="se"&gt;\"&lt;/span&gt;&lt;span class="s2"&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;There is also a &lt;code&gt;refreshInterval&lt;/code&gt; setting that re-runs the command on a fixed timer. You need it for clocks, or when the line depends on something that changes while the main session is idle.&lt;/p&gt;

&lt;h3&gt;
  
  
  A minimal working script
&lt;/h3&gt;

&lt;p&gt;Save this as &lt;code&gt;~/.claude/statusline.sh&lt;/code&gt;:&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;#!/bin/bash&lt;/span&gt;
&lt;span class="nv"&gt;input&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;cat&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;

&lt;span class="nv"&gt;MODEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.model.display_name'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;DIR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.workspace.current_dir'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;PCT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.context_window.used_percentage // 0'&lt;/span&gt; | &lt;span class="nb"&gt;cut&lt;/span&gt; &lt;span class="nt"&gt;-d&lt;/span&gt;&lt;span class="nb"&gt;.&lt;/span&gt; &lt;span class="nt"&gt;-f1&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"[&lt;/span&gt;&lt;span class="nv"&gt;$MODEL&lt;/span&gt;&lt;span class="s2"&gt;] &lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;DIR&lt;/span&gt;&lt;span class="p"&gt;##*/&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt; | &lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;PCT&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;% context"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then run &lt;code&gt;chmod +x ~/.claude/statusline.sh&lt;/code&gt;. Claude Code reloads settings automatically and runs the script as soon as you save the settings file.&lt;/p&gt;

&lt;p&gt;To test without starting a session, pipe in mock input:&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;echo&lt;/span&gt; &lt;span class="s1"&gt;'{"model":{"display_name":"Opus"},"workspace":{"current_dir":"/home/user/project"},"context_window":{"used_percentage":25},"session_id":"test-session-abc"}'&lt;/span&gt; | ~/.claude/statusline.sh
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  What data can the status line show?
&lt;/h2&gt;

&lt;p&gt;The JSON is larger than most people expect. These fields are the most useful day to day:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Field&lt;/th&gt;
&lt;th&gt;What it gives you&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;model.id&lt;/code&gt;, &lt;code&gt;model.display_name&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Current model&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;workspace.current_dir&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Where you are&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;workspace.git_worktree&lt;/code&gt;, &lt;code&gt;worktree.*&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Linked worktree details; only present inside one&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;context_window.used_percentage&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Percent of the context window used&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;cost.total_cost_usd&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Estimated session cost&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;cost.total_duration_ms&lt;/code&gt;, &lt;code&gt;cost.total_api_duration_ms&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Session time, and time spent waiting on the API&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;rate_limits.five_hour&lt;/code&gt;, &lt;code&gt;rate_limits.seven_day&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;used_percentage&lt;/code&gt; and &lt;code&gt;resets_at&lt;/code&gt; for each plan window&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;prompt_cache.*&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Cache warmth, hit ratio, misses&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;session_name&lt;/code&gt;, &lt;code&gt;agent.name&lt;/code&gt;, &lt;code&gt;pr.*&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Session label, active agent, open PR or merge request&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Two details matter for accuracy:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;used_percentage&lt;/code&gt; is calculated from input tokens only (&lt;code&gt;input_tokens + cache_creation_input_tokens + cache_read_input_tokens&lt;/code&gt;). Output tokens are not included. &lt;code&gt;/context&lt;/code&gt; can read higher because it adds an estimate for messages added since the last API response.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;cost.total_cost_usd&lt;/code&gt; is computed locally from token counts at list price, unless an administrator has set a &lt;code&gt;modelPricing&lt;/code&gt; table in managed settings. The cost docs call it an estimate. They also say that on Pro and Max the session cost figure is not relevant for billing, because usage is included in the subscription. The total resets to $0 when &lt;code&gt;/clear&lt;/code&gt; starts a new session.&lt;/li&gt;
&lt;/ul&gt;

&lt;h3&gt;
  
  
  Plan limits only appear for some accounts
&lt;/h3&gt;

&lt;p&gt;&lt;code&gt;rate_limits&lt;/code&gt; is present only for claude.ai Pro and Max subscribers (or behind a Claude apps gateway with a spend limit), and only after the first API response in a session. Each window can be absent on its own, and Claude Code drops a window once its &lt;code&gt;resets_at&lt;/code&gt; time passes. A script that assumes the field exists will misbehave on API-key setups.&lt;/p&gt;

&lt;h3&gt;
  
  
  Cache health
&lt;/h3&gt;

&lt;p&gt;The &lt;code&gt;prompt_cache&lt;/code&gt; object needs Claude Code v2.1.251 or later and appears after the main conversation's first API response. It includes &lt;code&gt;warm&lt;/code&gt;, &lt;code&gt;ttl&lt;/code&gt; (&lt;code&gt;"5m"&lt;/code&gt; or &lt;code&gt;"1h"&lt;/code&gt;), &lt;code&gt;expires_at&lt;/code&gt;, &lt;code&gt;hit_ratio&lt;/code&gt; (0 to 1) and &lt;code&gt;misses&lt;/code&gt;. From v2.1.260 it also reports a likely cause for the last miss, such as &lt;code&gt;tools_changed&lt;/code&gt;, &lt;code&gt;system_prompt_changed&lt;/code&gt; or &lt;code&gt;ttl_expired_5m&lt;/code&gt;. The same statistics appear on the &lt;code&gt;Prompt cache (main)&lt;/code&gt; line of &lt;code&gt;/usage&lt;/code&gt;. Subagent requests are not counted.&lt;/p&gt;

&lt;p&gt;A miss means a request re-processed content the cache already held. In the docs' definition, that is more than 5% and at least 2,000 tokens of what could have been read from cache, with no compaction or tool-result clearing to explain it.&lt;/p&gt;

&lt;h2&gt;
  
  
  A status line for context, cost and limits
&lt;/h2&gt;

&lt;p&gt;This script puts a colored context bar, cost and plan usage on one row, and copes with absent fields:&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;#!/bin/bash&lt;/span&gt;
&lt;span class="nv"&gt;input&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;cat&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;

&lt;span class="nv"&gt;MODEL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.model.display_name'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;PCT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.context_window.used_percentage // 0'&lt;/span&gt; | &lt;span class="nb"&gt;cut&lt;/span&gt; &lt;span class="nt"&gt;-d&lt;/span&gt;&lt;span class="nb"&gt;.&lt;/span&gt; &lt;span class="nt"&gt;-f1&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;COST&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.cost.total_cost_usd // 0'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;FIVE_H&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.rate_limits.five_hour.used_percentage // empty'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="nv"&gt;WEEK&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | jq &lt;span class="nt"&gt;-r&lt;/span&gt; &lt;span class="s1"&gt;'.rate_limits.seven_day.used_percentage // empty'&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;

&lt;span class="nv"&gt;GREEN&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'\033[32m'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nv"&gt;YELLOW&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'\033[33m'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nv"&gt;RED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'\033[31m'&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nv"&gt;RESET&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s1"&gt;'\033[0m'&lt;/span&gt;
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$PCT&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;-ge&lt;/span&gt; 90 &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then &lt;/span&gt;&lt;span class="nv"&gt;C&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$RED&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;elif&lt;/span&gt; &lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$PCT&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="nt"&gt;-ge&lt;/span&gt; 70 &lt;span class="o"&gt;]&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then &lt;/span&gt;&lt;span class="nv"&gt;C&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$YELLOW&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;
&lt;span class="k"&gt;else &lt;/span&gt;&lt;span class="nv"&gt;C&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$GREEN&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;fi

&lt;/span&gt;&lt;span class="nv"&gt;FILLED&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="k"&gt;$((&lt;/span&gt;PCT &lt;span class="o"&gt;/&lt;/span&gt; &lt;span class="m"&gt;10&lt;/span&gt;&lt;span class="k"&gt;))&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nv"&gt;EMPTY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="k"&gt;$((&lt;/span&gt;&lt;span class="m"&gt;10&lt;/span&gt; &lt;span class="o"&gt;-&lt;/span&gt; FILLED&lt;span class="k"&gt;))&lt;/span&gt;
&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt; FILL &lt;span class="s2"&gt;"%&lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;FILLED&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;s"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt; PAD &lt;span class="s2"&gt;"%&lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;EMPTY&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;s"&lt;/span&gt;
&lt;span class="nv"&gt;BAR&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;FILL&lt;/span&gt;&lt;span class="p"&gt;// /#&lt;/span&gt;&lt;span class="k"&gt;}${&lt;/span&gt;&lt;span class="nv"&gt;PAD&lt;/span&gt;&lt;span class="p"&gt;// /-&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;

&lt;span class="nv"&gt;LIMITS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;""&lt;/span&gt;
&lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="nt"&gt;-n&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$FIVE_H&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nv"&gt;LIMITS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;" | 5h &lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s1"&gt;'%.0f'&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$FIVE_H&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="s2"&gt;%"&lt;/span&gt;
&lt;span class="o"&gt;[&lt;/span&gt; &lt;span class="nt"&gt;-n&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$WEEK&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="o"&gt;]&lt;/span&gt; &lt;span class="o"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="nv"&gt;LIMITS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$LIMITS&lt;/span&gt;&lt;span class="s2"&gt; 7d &lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s1"&gt;'%.0f'&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$WEEK&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="s2"&gt;%"&lt;/span&gt;

&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="nt"&gt;-e&lt;/span&gt; &lt;span class="s2"&gt;"[&lt;/span&gt;&lt;span class="nv"&gt;$MODEL&lt;/span&gt;&lt;span class="s2"&gt;] &lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;C&lt;/span&gt;&lt;span class="k"&gt;}${&lt;/span&gt;&lt;span class="nv"&gt;BAR&lt;/span&gt;&lt;span class="k"&gt;}${&lt;/span&gt;&lt;span class="nv"&gt;RESET&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt; &lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;PCT&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;% | &lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;printf&lt;/span&gt; &lt;span class="s1"&gt;'$%.2f'&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$COST&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="k"&gt;${&lt;/span&gt;&lt;span class="nv"&gt;LIMITS&lt;/span&gt;&lt;span class="k"&gt;}&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The color thresholds (green under 70%, yellow 70 to 89%, red from 90%) match the docs' multi-line example; adjust them to taste. The &lt;code&gt;// empty&lt;/code&gt; idiom prints nothing when a field is missing, so the limits segment disappears for accounts without &lt;code&gt;rate_limits&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  How often does the status line run?
&lt;/h2&gt;

&lt;p&gt;It runs once when a session starts or resumes, then again when:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a new assistant message arrives&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;/compact&lt;/code&gt; finishes&lt;/li&gt;
&lt;li&gt;the permission mode changes&lt;/li&gt;
&lt;li&gt;vim mode toggles&lt;/li&gt;
&lt;li&gt;the &lt;code&gt;command&lt;/code&gt; in your settings changes&lt;/li&gt;
&lt;li&gt;a &lt;code&gt;refreshInterval&lt;/code&gt; timer elapses, if you set one&lt;/li&gt;
&lt;li&gt;a rate-limit window reaches its &lt;code&gt;resets_at&lt;/code&gt; time, or a warm prompt cache reaches its &lt;code&gt;expires_at&lt;/code&gt; time&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Updates are debounced at 300 ms, except that a change to the command itself runs right away. If a new update triggers while your script is still running, Claude Code cancels the in-flight run. The event-driven triggers can go quiet when the main session is idle, for example while a coordinator waits on background subagents. Set &lt;code&gt;refreshInterval&lt;/code&gt; if the line must stay current then.&lt;/p&gt;

&lt;h2&gt;
  
  
  Common problems and fixes
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;The line is blank.&lt;/strong&gt; Check these in turn:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;The script is not executable (&lt;code&gt;chmod +x&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;It writes to stderr instead of stdout.&lt;/li&gt;
&lt;li&gt;It exits non-zero or prints nothing. Claude Code displays output only after the script exits with code 0.&lt;/li&gt;
&lt;li&gt;You have not accepted the workspace trust dialog for the folder. Until then the line stays blank, and &lt;code&gt;claude --debug&lt;/code&gt; logs &lt;code&gt;Status line command skipped: workspace trust not accepted&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;disableAllHooks&lt;/code&gt; is &lt;code&gt;true&lt;/code&gt; outside managed settings, in which case only a &lt;code&gt;statusLine&lt;/code&gt; from managed settings runs. Or your organization sets &lt;code&gt;allowManagedHooksOnly&lt;/code&gt;, which means you can only get a status line from managed settings.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;code&gt;claude --debug&lt;/code&gt; logs your script's stderr on every invocation and its exit code on the first one in a session, which makes it the quickest way to find a parse error.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Values show &lt;code&gt;--&lt;/code&gt; or empty.&lt;/strong&gt; Fields can be &lt;code&gt;null&lt;/code&gt; before the first API response. &lt;code&gt;context_window.used_percentage&lt;/code&gt; may be &lt;code&gt;null&lt;/code&gt; early in a session, and &lt;code&gt;context_window.current_usage&lt;/code&gt; is &lt;code&gt;null&lt;/code&gt; again right after &lt;code&gt;/compact&lt;/code&gt; until the next API call. Use fallbacks such as &lt;code&gt;// 0&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The line lags.&lt;/strong&gt; The script runs often, and &lt;code&gt;git status&lt;/code&gt; or &lt;code&gt;git diff&lt;/code&gt; in a large repo is slow. Cache the result in a temp file for a few seconds. Key the cache on &lt;code&gt;session_id&lt;/code&gt; from the JSON, not on &lt;code&gt;$$&lt;/code&gt;: a process ID changes on every invocation and defeats the cache, while &lt;code&gt;session_id&lt;/code&gt; is stable within a session and unique across concurrent ones. The docs include a full example that refreshes git info every 5 seconds.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Links are not clickable.&lt;/strong&gt; Terminal.app does not support them. If your terminal does but the link text is not clickable, Claude Code may not have detected hyperlink support; launch with &lt;code&gt;FORCE_HYPERLINK=1 claude&lt;/code&gt;. SSH and tmux can strip the escape sequences. If escape codes show up as literal text, use &lt;code&gt;printf '%b'&lt;/code&gt; instead of &lt;code&gt;echo -e&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Windows paths.&lt;/strong&gt; With Git Bash, write paths in &lt;code&gt;command&lt;/code&gt; with forward slashes. Unquoted backslashes are treated as escape characters, and the command fails without a visible error.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Garbled output.&lt;/strong&gt; Complex escape sequences, especially in multi-line status lines, can occasionally corrupt the display. Simplify to plain text if you see it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Status lines for subagents
&lt;/h2&gt;

&lt;p&gt;A separate &lt;code&gt;subagentStatusLine&lt;/code&gt; setting customizes the row shown for each subagent in the agent panel. Its command runs once per refresh tick and receives all visible rows as one JSON object, with a &lt;code&gt;tasks&lt;/code&gt; array whose entries include fields such as &lt;code&gt;name&lt;/code&gt;, &lt;code&gt;status&lt;/code&gt;, &lt;code&gt;model&lt;/code&gt;, &lt;code&gt;tokenCount&lt;/code&gt; and &lt;code&gt;contextWindowSize&lt;/code&gt;. You answer with one JSON line per row, in the form &lt;code&gt;{"id": "&amp;lt;task id&amp;gt;", "content": "&amp;lt;row body&amp;gt;"}&lt;/code&gt;. Omit &lt;code&gt;id&lt;/code&gt; to keep the default row; send an empty &lt;code&gt;content&lt;/code&gt; to hide it. The same trust, &lt;code&gt;disableAllHooks&lt;/code&gt; and &lt;code&gt;allowManagedHooksOnly&lt;/code&gt; gates apply as for &lt;code&gt;statusLine&lt;/code&gt;. If you split work across helpers, this is a cheap way to see which one is using the most tokens.&lt;/p&gt;

&lt;h2&gt;
  
  
  Should the status line be shared with a team?
&lt;/h2&gt;

&lt;p&gt;Because &lt;code&gt;statusLine&lt;/code&gt; executes a shell command, it falls under the same workspace-trust rule as hooks in settings files. A project-level status line therefore runs code from the repository on whoever trusts the folder. Keep shared scripts small and reviewable, and prefer user settings for personal preferences. Plugins can ship a default &lt;code&gt;subagentStatusLine&lt;/code&gt;, but unlike hooks, those values do not run under &lt;code&gt;allowManagedHooksOnly&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;A status line is a small script that keeps context fill, estimated cost and plan usage in front of you, so you can compact or start fresh before a session gets expensive. Start with &lt;code&gt;/statusline&lt;/code&gt;, move to a hand-written script once you know which fields you read, guard every optional field, and cache anything slow. Treat the cost figure as an estimate; for authoritative billing, the cost docs point to the Usage page in the Claude Console.&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/statusline" rel="noopener noreferrer"&gt;Customize your status line - Claude Code Docs&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/costs" rel="noopener noreferrer"&gt;Manage costs effectively - Claude Code Docs&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/claude-code-status-line-context-cost-limits/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-status-line-context-cost-limits" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>claudecode</category>
      <category>ai</category>
      <category>productivity</category>
      <category>bash</category>
    </item>
    <item>
      <title>AI Coding Agent Usage Limits Explained in Plain English</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Tue, 27 Oct 2026 13:00:00 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/ai-coding-agent-usage-limits-explained-in-plain-english-2df4</link>
      <guid>https://dev.to/nixonperinchery/ai-coding-agent-usage-limits-explained-in-plain-english-2df4</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Pro and Max plans have a five-hour session limit and a weekly limit, and Claude chat and Claude Code draw from the same allowance.&lt;/li&gt;
&lt;li&gt;At the limit the agent stops, or may be allowed to finish its current step. Files already changed stay changed; you wait for the reset, upgrade, or turn on usage credits.&lt;/li&gt;
&lt;li&gt;Long conversations, bigger models, higher effort and many connected tools use the allowance faster, so short, focused sessions stretch it further.&lt;/li&gt;
&lt;li&gt;Several AI engineers working at once use the plan faster, so size the plan to the amount of parallel work.&lt;/li&gt;
&lt;li&gt;Usage credits and API credits are billed at standard API rates, outside the plan price, so decide who may turn them on before you hit the wall.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;If your AI coding agent suddenly stops and says a limit has been reached, you have not broken anything. On Claude Pro and Max plans, Claude Code runs against a usage allowance, and that allowance has two main parts: a limit for each five-hour session and a limit for each week. When you reach one, the agent stops until it resets, or until you pay for more.&lt;/p&gt;

&lt;p&gt;This guide explains those limits in plain English, what uses them up, and how a founder, product owner or manager can plan around them.&lt;/p&gt;

&lt;h2&gt;
  
  
  What are AI coding agent usage limits?
&lt;/h2&gt;

&lt;p&gt;Think of a mobile data plan, but with two meters instead of one. Anthropic's help pages say that both Pro and Max have a five-hour session limit and a weekly limit. Max plans also have a separate weekly limit for Fable, which sits apart from the general weekly limit.&lt;/p&gt;

&lt;p&gt;Paid plans have a session limit that resets every five hours and weekly limits that reset once a week. Anthropic's help pages give no exact message counts or token numbers, so nobody can tell you in advance "you get exactly this many tasks." What you can learn is how fast your own work uses the meters. (A "token" is a small chunk of text the AI reads or writes, and it is the unit usage is counted in.)&lt;/p&gt;

&lt;h2&gt;
  
  
  Are chat and coding counted together?
&lt;/h2&gt;

&lt;p&gt;Yes. Usage on the Claude chat app, Claude Code and Claude Desktop counts toward the same limit, and Anthropic says usage in code editors counts too. If a colleague spends the morning asking Claude questions on the same account, that comes out of the same allowance your coding agent needs in the afternoon.&lt;/p&gt;

&lt;p&gt;This surprises many teams. If one login is shared by several people, or one person uses the chat heavily, the coding agent can hit the wall earlier than expected.&lt;/p&gt;

&lt;h2&gt;
  
  
  What happens when you hit the limit?
&lt;/h2&gt;

&lt;p&gt;Anthropic says you get warning messages as you approach a limit. If you reach the five-hour limit in the middle of a response, Claude Code may be allowed to finish its current step, and you would see the message "Usage limit reached · wrapping up." That extra allowance is small and capped, it counts toward your weekly limit, and it covers only a response already in progress, not a new message you send afterwards.&lt;/p&gt;

&lt;p&gt;Anthropic says it is rolling out gradually, so it may not be on your account yet. On Pro it applies up to once per weekly period. On Max it can apply each time you reach a five-hour limit, within the weekly limit.&lt;/p&gt;

&lt;p&gt;After that, the agent stops. The files it already changed stay changed, so you are waiting, not losing work. It is still wise to ask the agent to leave short notes on where it stopped, so the next session can pick up cleanly.&lt;/p&gt;

&lt;h2&gt;
  
  
  What uses up the allowance fastest?
&lt;/h2&gt;

&lt;p&gt;Anthropic points to these factors:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Length and complexity of the conversation.&lt;/strong&gt; A long, wandering session costs more than a short, focused one. Very long conversations also trigger automatic context management, which uses more of your limit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The model you pick.&lt;/strong&gt; Model choice affects how quickly usage is consumed.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The effort level.&lt;/strong&gt; Higher effort uses more tokens, so asking the agent to think hard on every small task adds up.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tools and connectors.&lt;/strong&gt; Anthropic describes these as token-intensive.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A plain example: asking the agent to rename a button label is a cheap job. Asking it to redesign checkout, read the whole codebase, run tests and fix what fails is an expensive one. Ten of the second kind in a day will empty a meter sooner than ten of the first. This is our own illustration, not an Anthropic figure.&lt;/p&gt;

&lt;h2&gt;
  
  
  How can I make the allowance last longer?
&lt;/h2&gt;

&lt;p&gt;Anthropic's own tips are simple, and you can ask your team to follow them:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Start a new conversation when a long one nears your limit.&lt;/li&gt;
&lt;li&gt;Use a lower effort level for routine work.&lt;/li&gt;
&lt;li&gt;Turn off extended thinking when you do not need it.&lt;/li&gt;
&lt;li&gt;Turn off connected apps and tools you are not using.&lt;/li&gt;
&lt;li&gt;Remove unused project files and keep the project's instructions short.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;For a non-technical manager, the most useful habit is the first one: give the agent one clear job at a time. A clear brief should also help, because the agent has less to guess at, though that is common sense rather than something Anthropic measures.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why do several AI engineers hit the limit sooner?
&lt;/h2&gt;

&lt;p&gt;If you run a team of AI engineers, each one is its own working session, and all of them draw from the same plan. More engineers working in parallel will use the allowance faster than one working alone. That is the trade: you finish sooner on the clock, but you also reach the meters sooner.&lt;/p&gt;

&lt;p&gt;So match the size of the plan to the amount of parallel work. Anthropic suggests that a Pro user who regularly hits limits consider Max 5x, and that someone on Max 5x who regularly hits them consider Max 20x. The help pages give no price or capacity figures for the tiers, so check the current pricing page before you decide.&lt;/p&gt;

&lt;h2&gt;
  
  
  What are my options when I hit the wall?
&lt;/h2&gt;

&lt;p&gt;Anthropic lists these choices:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Wait for the reset.&lt;/strong&gt; Free, and fine if the work is not urgent.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Upgrade your plan.&lt;/strong&gt; The new limits apply right away.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Turn on usage credits.&lt;/strong&gt; Work carries on instead of stopping, but this is extra spending beyond your plan. Pro, Max and Team plans can buy them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use a developer (Console) account with API credits.&lt;/strong&gt; Billed at standard API rates, which are separate from plan pricing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Two cautions. First, extra usage is real money, so decide in advance who may switch it on and what the ceiling is. Second, if the &lt;code&gt;ANTHROPIC_API_KEY&lt;/code&gt; setting exists on the machine, Claude Code uses that key instead of your subscription, and you are charged per use. If you meant to stay on the plan, ask someone technical to check this. Anthropic says you can see your remaining allocation with the &lt;code&gt;/status&lt;/code&gt; command, and that you can decline the API credit option when it is offered.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I plan work around the limits?
&lt;/h2&gt;

&lt;p&gt;A few practical rules. They are our suggestions, not Anthropic's:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Do the heavy work early in the week.&lt;/strong&gt; Save small fixes and polish for when the meter is low.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Start big jobs at the beginning of a session.&lt;/strong&gt; Do not begin a large build when you are nearly out.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep a buffer.&lt;/strong&gt; Do not run the plan to the limit in the middle of a release. A stop on release day is the worst time.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Watch the trend.&lt;/strong&gt; If you reach the weekly limit early every week, either the work is too big for the plan or the sessions are too long.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  What Atlas does today
&lt;/h2&gt;

&lt;p&gt;Atlas is a team of AI engineers built on Claude Code. It runs on your own Claude Pro or Max plan, signed in with that plan, with no API keys and no per-token bill, so usage counts against the plan. Several engineers working at once use the plan's limits faster, and Max gives the most room. Atlas's price never includes Claude.&lt;/p&gt;

&lt;p&gt;Atlas also has an optional daily budget that warns at 50% and 80% and pauses the team at 100%. Production go-lives, spending and deleting data are never decided for you.&lt;/p&gt;

&lt;p&gt;Atlas does not yet let you set a stop point tied to the five-hour or weekly plan limits. That is coming to Atlas, built in, so it needs no setup. Until then, use the daily budget, watch your remaining allocation with &lt;code&gt;/status&lt;/code&gt;, and follow the planning rules above.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Usage limits are not a fault; they are the shape of the plan you bought. Know the two meters, keep sessions short and focused, and decide in advance whether you will wait, upgrade or pay for extra. Then a limit becomes a scheduling detail instead of a surprise. The &lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=ai-coding-agent-usage-limits-plain-english" rel="noopener noreferrer"&gt;Atlas home page&lt;/a&gt; has more plain-language guides.&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/11145838-using-claude-code-with-your-pro-or-max-plan" rel="noopener noreferrer"&gt;Using Claude Code with your Pro or Max plan&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?&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=ai-coding-agent-usage-limits-plain-english" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>claudecode</category>
      <category>ai</category>
      <category>productivity</category>
      <category>beginners</category>
    </item>
    <item>
      <title>Claude Code OpenTelemetry: Track Cost and Tool Use</title>
      <dc:creator>Nixon Perinchery</dc:creator>
      <pubDate>Mon, 26 Oct 2026 12:58:52 +0000</pubDate>
      <link>https://dev.to/nixonperinchery/claude-code-opentelemetry-track-cost-and-tool-use-c83</link>
      <guid>https://dev.to/nixonperinchery/claude-code-opentelemetry-track-cost-and-tool-use-c83</guid>
      <description>&lt;p&gt;&lt;strong&gt;The short version&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Code exports usage metrics and events through OpenTelemetry once you set CLAUDE_CODE_ENABLE_TELEMETRY=1 and choose an exporter.&lt;/li&gt;
&lt;li&gt;A repository cannot switch telemetry on or point it somewhere: OTEL exporter variables in project settings files are ignored, so rollout belongs in managed settings.&lt;/li&gt;
&lt;li&gt;Prompt text, tool details and raw API bodies are off by default, and each has its own opt-in flag.&lt;/li&gt;
&lt;li&gt;Cost and token metrics can be split by model, subagent, skill, plugin and MCP server, which shows what drives your spend.&lt;/li&gt;
&lt;li&gt;The dollar figures are local estimates at list price (or your configured rates), not a bill. On Pro and Max plans usage is included in the subscription, so use the figures to compare, not to invoice.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;To monitor Claude Code usage across a team, turn on its built-in OpenTelemetry export: set &lt;code&gt;CLAUDE_CODE_ENABLE_TELEMETRY=1&lt;/code&gt;, pick an exporter, and point it at a collector. You then get token, cost, commit, pull request and tool-decision data in your own observability stack, tagged by model, subagent, skill and MCP server.&lt;/p&gt;

&lt;p&gt;The Claude Code docs describe OpenTelemetry export as working on every setup and as the only option that streams per-user token and cost metrics into your own stack in near real time. This guide covers the minimum setup, a managed-settings rollout, the privacy switches, and the questions the data can answer.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why export telemetry instead of reading /usage?
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;/usage&lt;/code&gt; is per machine. Its breakdown is computed from local session history, so usage from other devices or claude.ai is not included. That is fine for one developer and no help for a team that wants to compare weeks, repos or workflows.&lt;/p&gt;

&lt;p&gt;Telemetry sends the signals to one place. The docs' comparison for organizations lists the alternatives by setup: the spend report and analytics dashboard on Teams and Enterprise, the Console dashboard and Claude Code Analytics API for API customers, and your cloud's billing console on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry. On the cloud providers, OpenTelemetry (or an LLM gateway) is how you get per-user numbers.&lt;/p&gt;

&lt;p&gt;One caveat up front: Claude Code computes dollar figures locally from token counts at list price. Pro and Max subscribers have usage included in the subscription, so a cost figure there is not a billing number. Even for API users the docs call it an estimate; the Console usage page is authoritative.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I turn on Claude Code OpenTelemetry?
&lt;/h2&gt;

&lt;p&gt;Set environment variables before starting Claude Code. These are the documented basics:&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_ENABLE_TELEMETRY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1          &lt;span class="c"&gt;# required&lt;/span&gt;
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_METRICS_EXPORTER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;otlp              &lt;span class="c"&gt;# otlp, prometheus, console, none&lt;/span&gt;
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_LOGS_EXPORTER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;otlp                 &lt;span class="c"&gt;# otlp, console, none&lt;/span&gt;
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_PROTOCOL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;grpc        &lt;span class="c"&gt;# grpc, http/json, http/protobuf&lt;/span&gt;
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_ENDPOINT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;http://localhost:4317
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_HEADERS&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="s2"&gt;"Authorization=Bearer your-token"&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;There is no default protocol, so set &lt;code&gt;OTEL_EXPORTER_OTLP_PROTOCOL&lt;/code&gt; (or the per-signal protocol variable) for each OTLP exporter you enable. Metrics export every 60 seconds by default (&lt;code&gt;OTEL_METRIC_EXPORT_INTERVAL&lt;/code&gt;, in milliseconds) and logs every 5 seconds (&lt;code&gt;OTEL_LOGS_EXPORT_INTERVAL&lt;/code&gt;).&lt;/p&gt;

&lt;h3&gt;
  
  
  Test locally first
&lt;/h3&gt;

&lt;p&gt;Before you involve a collector, print metrics to the terminal at a one-second interval:&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_ENABLE_TELEMETRY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_METRICS_EXPORTER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;console
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_METRIC_EXPORT_INTERVAL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1000
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Or expose a Prometheus endpoint and scrape &lt;code&gt;http://localhost:9464/metrics&lt;/code&gt;:&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_ENABLE_TELEMETRY&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;1
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_METRICS_EXPORTER&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;prometheus
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;To confirm a metrics pipeline works, look for &lt;code&gt;claude_code.session.count&lt;/code&gt;, which is emitted at session start. For a logs-only setup, submit a prompt and look for the &lt;code&gt;claude_code.user_prompt&lt;/code&gt; event. If nothing arrives, start Claude Code with &lt;code&gt;claude --debug-file &amp;lt;path&amp;gt;&lt;/code&gt; and search the file for &lt;code&gt;[3P telemetry]&lt;/code&gt; errors. Lines tagged &lt;code&gt;[Anthropic telemetry]&lt;/code&gt; describe Anthropic's own operational telemetry and do not point to a problem with your setup.&lt;/p&gt;

&lt;h3&gt;
  
  
  Send metrics and logs to different backends
&lt;/h3&gt;

&lt;p&gt;Per-signal variables override the generic ones:&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;OTEL_EXPORTER_OTLP_METRICS_PROTOCOL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;http/protobuf
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_METRICS_ENDPOINT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;http://metrics.example.com:4318
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_LOGS_PROTOCOL&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;grpc
&lt;span class="nb"&gt;export &lt;/span&gt;&lt;span class="nv"&gt;OTEL_EXPORTER_OTLP_LOGS_ENDPOINT&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;http://logs.example.com:4317
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Per-signal headers merge with the generic &lt;code&gt;OTEL_EXPORTER_OTLP_HEADERS&lt;/code&gt;. Metric temporality defaults to &lt;code&gt;delta&lt;/code&gt;; set &lt;code&gt;OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative&lt;/code&gt; if your backend expects that.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I roll it out to a whole team?
&lt;/h2&gt;

&lt;p&gt;Put the variables in the managed settings file so they apply to every user:&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;"env"&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_CODE_ENABLE_TELEMETRY"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OTEL_METRICS_EXPORTER"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"otlp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OTEL_LOGS_EXPORTER"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"otlp"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OTEL_EXPORTER_OTLP_PROTOCOL"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"grpc"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OTEL_EXPORTER_OTLP_ENDPOINT"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"http://collector.example.com:4317"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"OTEL_EXPORTER_OTLP_HEADERS"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Authorization=Bearer example-token"&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;Four behaviours matter here, all from the docs:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Code ignores &lt;code&gt;OTEL_*&lt;/code&gt; exporter variables in &lt;code&gt;.claude/settings.json&lt;/code&gt; and &lt;code&gt;.claude/settings.local.json&lt;/code&gt;. A repository cannot enable telemetry, choose a destination or capture content. It can still set an exporter selector to &lt;code&gt;none&lt;/code&gt; to turn a signal off, unless managed settings, a &lt;code&gt;--settings&lt;/code&gt; file or the starting environment already sets that variable.&lt;/li&gt;
&lt;li&gt;Setting &lt;code&gt;OTEL_EXPORTER_OTLP_ENDPOINT&lt;/code&gt; in managed settings removes developer-set per-signal endpoints. Setting the protocol removes developer-set per-signal protocols. Setting headers or client key and certificate variables removes the developer-set per-signal versions of that variable and all developer-set endpoints.&lt;/li&gt;
&lt;li&gt;The exporter selectors (&lt;code&gt;OTEL_METRICS_EXPORTER&lt;/code&gt;, &lt;code&gt;OTEL_LOGS_EXPORTER&lt;/code&gt;, &lt;code&gt;OTEL_TRACES_EXPORTER&lt;/code&gt;) are not locked by those endpoint rules. To lock them, set them in managed settings too; the docs say this needs v2.1.223 or later.&lt;/li&gt;
&lt;li&gt;Claude Code does not pass &lt;code&gt;OTEL_*&lt;/code&gt; variables to subprocesses such as the Bash tool, hooks, MCP servers or language servers, so your own scripts do not inherit your collector credentials.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;The first point is a useful safety property: a cloned repo cannot quietly redirect your telemetry.&lt;/p&gt;

&lt;h2&gt;
  
  
  What does Claude Code measure?
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Metrics
&lt;/h3&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Metric&lt;/th&gt;
&lt;th&gt;What it counts&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.session.count&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Sessions, with &lt;code&gt;start_type&lt;/code&gt;: &lt;code&gt;fresh&lt;/code&gt;, &lt;code&gt;resume&lt;/code&gt;, &lt;code&gt;continue&lt;/code&gt;, &lt;code&gt;agents_view&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.lines_of_code.count&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Lines, &lt;code&gt;type&lt;/code&gt; &lt;code&gt;added&lt;/code&gt; or &lt;code&gt;removed&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.pull_request.count&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Pull requests&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.commit.count&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Commits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.cost.usage&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Estimated USD cost, per API request&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.token.usage&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Tokens by &lt;code&gt;type&lt;/code&gt;: &lt;code&gt;input&lt;/code&gt;, &lt;code&gt;output&lt;/code&gt;, &lt;code&gt;cacheRead&lt;/code&gt;, &lt;code&gt;cacheCreation&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.code_edit_tool.decision&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Accept or reject decisions for edit tools, with &lt;code&gt;tool_name&lt;/code&gt;, &lt;code&gt;decision&lt;/code&gt;, &lt;code&gt;source&lt;/code&gt;, &lt;code&gt;language&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;claude_code.active_time.total&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Seconds, split into &lt;code&gt;user&lt;/code&gt; (keyboard) and &lt;code&gt;cli&lt;/code&gt; (tools and responses)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Cost and token metrics also carry &lt;code&gt;model&lt;/code&gt;, &lt;code&gt;query_source&lt;/code&gt; (&lt;code&gt;main&lt;/code&gt;, &lt;code&gt;subagent&lt;/code&gt; or &lt;code&gt;auxiliary&lt;/code&gt;), &lt;code&gt;speed&lt;/code&gt;, &lt;code&gt;effort&lt;/code&gt;, &lt;code&gt;agent.name&lt;/code&gt;, &lt;code&gt;skill.name&lt;/code&gt;, &lt;code&gt;plugin.name&lt;/code&gt;, &lt;code&gt;mcp_server.name&lt;/code&gt; and &lt;code&gt;mcp_tool.name&lt;/code&gt;. That attribution is the valuable part: it lets you ask whether spend comes from the main conversation, a subagent, one skill or one MCP server.&lt;/p&gt;

&lt;p&gt;Agent, skill, plugin and MCP names are redacted to &lt;code&gt;custom&lt;/code&gt; or &lt;code&gt;third-party&lt;/code&gt; unless &lt;code&gt;OTEL_LOG_TOOL_DETAILS=1&lt;/code&gt; is set.&lt;/p&gt;

&lt;h3&gt;
  
  
  Events
&lt;/h3&gt;

&lt;p&gt;Events go through the logs exporter and share a &lt;code&gt;claude_code.&lt;/code&gt; prefix. The useful ones:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;api_request&lt;/code&gt;: model, &lt;code&gt;cost_usd&lt;/code&gt;, &lt;code&gt;duration_ms&lt;/code&gt;, token counts, &lt;code&gt;request_id&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;api_error&lt;/code&gt;: &lt;code&gt;error&lt;/code&gt;, &lt;code&gt;status_code&lt;/code&gt;, &lt;code&gt;attempt&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;tool_result&lt;/code&gt;: &lt;code&gt;tool_name&lt;/code&gt;, &lt;code&gt;tool_use_id&lt;/code&gt;, &lt;code&gt;success&lt;/code&gt;, &lt;code&gt;duration_ms&lt;/code&gt;, &lt;code&gt;decision_source&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;tool_decision&lt;/code&gt;: &lt;code&gt;decision&lt;/code&gt; (&lt;code&gt;accept&lt;/code&gt; or &lt;code&gt;reject&lt;/code&gt;), &lt;code&gt;source&lt;/code&gt;, &lt;code&gt;permission_mode&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;user_prompt&lt;/code&gt; and &lt;code&gt;assistant_response&lt;/code&gt;: lengths by default, content only if you opt in.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;code&gt;prompt.id&lt;/code&gt; links every event from one prompt. &lt;code&gt;event.sequence&lt;/code&gt; is a per-process counter, so sort by &lt;code&gt;event.timestamp&lt;/code&gt; first. With those you can reconstruct what one instruction cost and which tools it touched.&lt;/p&gt;

&lt;h3&gt;
  
  
  Traces (beta)
&lt;/h3&gt;

&lt;p&gt;Set &lt;code&gt;CLAUDE_CODE_ENABLE_TELEMETRY=1&lt;/code&gt; and &lt;code&gt;CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1&lt;/code&gt;, then choose &lt;code&gt;OTEL_TRACES_EXPORTER&lt;/code&gt;. Spans run from &lt;code&gt;claude_code.interaction&lt;/code&gt;, the root span for each prompt, down to &lt;code&gt;claude_code.llm_request&lt;/code&gt; and &lt;code&gt;claude_code.tool&lt;/code&gt;, which has &lt;code&gt;blocked_on_user&lt;/code&gt; and &lt;code&gt;execution&lt;/code&gt; children. The blocked-on-user span shows how long work waited for a permission answer. The &lt;code&gt;claude_code.hook&lt;/code&gt; span needs extra settings (&lt;code&gt;ENABLE_BETA_TRACING_DETAILED=1&lt;/code&gt; and &lt;code&gt;BETA_TRACING_ENDPOINT&lt;/code&gt;), and interactive CLI sessions also need organization allowlisting.&lt;/p&gt;

&lt;h2&gt;
  
  
  What should I keep private?
&lt;/h2&gt;

&lt;p&gt;Content capture is off by default. Opt in deliberately:&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;Effect&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_LOG_USER_PROMPTS=1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Prompt text in &lt;code&gt;user_prompt&lt;/code&gt;; otherwise &lt;code&gt;&amp;lt;REDACTED&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_LOG_ASSISTANT_RESPONSES=1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Response text; follows the prompts flag if unset, &lt;code&gt;0&lt;/code&gt; keeps it redacted&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_LOG_TOOL_DETAILS=1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Tool parameters, Bash commands, MCP and skill names, full error messages&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_LOG_TOOL_CONTENT=1&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;Tool output in a span event (needs tracing)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;
&lt;code&gt;OTEL_LOG_RAW_API_BODIES=1&lt;/code&gt; or &lt;code&gt;file:&amp;lt;dir&amp;gt;&lt;/code&gt;
&lt;/td&gt;
&lt;td&gt;Full API request and response bodies, inline or as untruncated files on disk&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Treat the last one as sensitive data storage, since the bodies carry whatever the conversation contained. Content attributes are truncated at 60 KB by default (&lt;code&gt;CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH&lt;/code&gt;). A sensible team default is metrics plus event metadata, with tool details on only if you want per-skill and per-server attribution and your policy allows commands in logs.&lt;/p&gt;

&lt;p&gt;Standard attributes include &lt;code&gt;session.id&lt;/code&gt;, &lt;code&gt;user.account_uuid&lt;/code&gt;, &lt;code&gt;user.id&lt;/code&gt; (a random anonymous ID) and &lt;code&gt;user.email&lt;/code&gt;. If you do not want per-person data, check what your collector keeps.&lt;/p&gt;

&lt;h2&gt;
  
  
  How do I keep metric cardinality under control?
&lt;/h2&gt;

&lt;p&gt;Every attribute multiplies series in your backend. Defaults:&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;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_SESSION_ID&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;true&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_ACCOUNT_UUID&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;true&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;true&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_VERSION&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;false&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_ENTRYPOINT&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;false&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;OTEL_METRICS_INCLUDE_REPOSITORY&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;
&lt;code&gt;false&lt;/code&gt; (v2.1.269 and later)&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Session ID is the usual culprit, since every session creates a new series. If you only chart by team or model, set &lt;code&gt;OTEL_METRICS_INCLUDE_SESSION_ID=false&lt;/code&gt;. To add your own dimensions, use &lt;code&gt;OTEL_RESOURCE_ATTRIBUTES&lt;/code&gt;, for example &lt;code&gt;department=engineering,team.id=platform&lt;/code&gt;. Values cannot contain spaces, and quotes do not escape them.&lt;/p&gt;

&lt;h2&gt;
  
  
  What questions can the data answer?
&lt;/h2&gt;

&lt;p&gt;Start with four panels:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Tokens by type over time.&lt;/strong&gt; A high &lt;code&gt;cacheCreation&lt;/code&gt; share next to low &lt;code&gt;cacheRead&lt;/code&gt; suggests sessions keep rebuilding context, for example after long idle gaps.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Cost by &lt;code&gt;agent.name&lt;/code&gt;, &lt;code&gt;skill.name&lt;/code&gt; and &lt;code&gt;mcp_server.name&lt;/code&gt;.&lt;/strong&gt; This shows whether a subagent or an MCP server dominates. Turn on &lt;code&gt;OTEL_LOG_TOOL_DETAILS=1&lt;/code&gt; to see real names.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;tool_decision&lt;/code&gt; rejects and &lt;code&gt;blocked_on_user&lt;/code&gt; time.&lt;/strong&gt; Many prompts waiting on a person point to permission rules that need tuning.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;api_error&lt;/code&gt; by &lt;code&gt;status_code&lt;/code&gt;.&lt;/strong&gt; Rising errors or retries explain slow sessions better than guessing.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Use the same data to check changes. If you move a task type to a smaller model or lower effort, compare &lt;code&gt;claude_code.cost.usage&lt;/code&gt; split by &lt;code&gt;model&lt;/code&gt; and &lt;code&gt;effort&lt;/code&gt; before and after, rather than trusting a feeling.&lt;/p&gt;

&lt;p&gt;Where an organization pays contracted rates, the docs say cost figures, including OpenTelemetry, stay at list price unless an administrator sets the &lt;code&gt;modelPricing&lt;/code&gt; managed setting (Claude Code v2.1.242 or later). That changes what is reported, not what is charged.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where does Atlas fit?
&lt;/h2&gt;

&lt;p&gt;Atlas is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session, signed in with your own Claude Pro or Max plan, so there are no API keys and no per-token bill. Several engineers at once use the plan's limits faster, and Max gives the most room. Atlas has an optional daily budget that warns at 50% and 80% and pauses the team at 100%, and a Network screen shows what every engineer is doing live.&lt;/p&gt;

&lt;p&gt;Atlas does not export OpenTelemetry data today. Streaming the team's activity to a collector you own is coming to Atlas, built in, so it will need no setup on your side. Until then, if you run Claude Code yourself, the setup above works as written. Atlas is an independent product. Learn more at &lt;a href="https://bridge-terminal.com/atlas/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-opentelemetry-monitor-cost-usage" rel="noopener noreferrer"&gt;Atlas&lt;/a&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Telemetry is a small config change that gives you one place to see tokens, estimated cost and tool behaviour across everyone. Start with the console exporter on one machine, move to a collector, then enforce the settings through managed settings so a repository cannot change them. Keep prompt and API-body capture off unless you have a clear reason, and drop session ID from metrics if your backend struggles.&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/monitoring-usage" rel="noopener noreferrer"&gt;Claude Code OpenTelemetry reference (monitoring usage)&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href="https://code.claude.com/docs/en/costs" rel="noopener noreferrer"&gt;Manage costs effectively - Claude Code docs&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;&lt;em&gt;Originally published on the &lt;a href="https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/?utm_source=devto&amp;amp;utm_medium=crosspost&amp;amp;utm_campaign=claude-code-opentelemetry-monitor-cost-usage" rel="noopener noreferrer"&gt;Atlas blog&lt;/a&gt;.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>claudecode</category>
      <category>opentelemetry</category>
      <category>ai</category>
      <category>devops</category>
    </item>
  </channel>
</rss>
