# Atlas — full content > Atlas is a software team made of AI engineers, built on Claude Code — it runs on your own Claude account, in Claude Code's terminal mode, with no API keys or per-token API bill. You talk to one of them — PA, your project assistant — in plain words; PA shares the work out to specialists who design, build, test and security-check it, and releases it when you say so. Generated: 2026-10-26. The core pages, the newest 33 of 44 articles (every article is listed at https://bridge-terminal.com/atlas/blog/index.md, each with its own Markdown copy) and the legal pages. A page's own address is given above it. --- # Atlas — an AI software team built on Claude Code > Atlas's home page. Atlas is a Mac app that runs a software team of AI engineers on your own Claude Code account: you talk to PA in plain words, and specialists design, build, test, review and release the work, on your Mac or on your company's own DigitalOcean server. The page covers how the team works, testing, recordings turned into fixes, where it runs and the decisions it never makes for you. Canonical: https://bridge-terminal.com/atlas/ Last updated: 2026-10-26 An engineering team built from Claude Code ## Say what you want built. _A team builds it._ Atlas is a software team made of AI engineers. You talk to one of them — **PA**, your project assistant — in plain words. PA shares the work out to specialists who design it, build it, test it and check it is safe, and when you say so, it goes live. [Download for Mac](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) [Talk to us](mailto:atlas@bridge-terminal.com?subject=Atlas) For Macs with Apple silicon · needs your own Claude account with Claude Code · one project free on your Mac · 30 days free on your server · [pricing](https://bridge-terminal.com/atlas/pricing.html) [**Bring your own Claude Code.** Atlas runs in Claude Code’s terminal mode, signed in with your own Claude plan — no API keys, no per-token API bill. _Do more with less →_](https://bridge-terminal.com/atlas/#your-claude) _An illustration of the live network: PA in the middle, each engineer around it, the busy ones showing what they are doing, and engineers also messaging each other directly_ ### You talk. It gets built. 1. **Say it the way you would say it to a person.** “I want a booking site for my salon, where customers pick a time and pay a deposit.” No forms, no jargon. 2. **PA asks what it needs to know.** Who it is for and what matters most — then it writes the plan down, so nothing is guessed. 3. **The team shares out the work.** A designer draws the screens, builders write the code, testers try to break it and a security engineer looks for holes — at the same time, as in the picture above. 4. **You see proof, not promises.** Nothing counts as finished until it is tested and clicked through in a real browser, with screenshots you can open. When the team needs a decision, PA asks you, one question at a time. ### Say the word. It goes live. 1. **Start on your Mac.** The team works inside the Atlas app while you try things out. One project in development at a time is free. 2. **Move the team to your company’s server when you like.** Sign in with DigitalOcean once and Atlas sets up a server in your own account. The project moves across in one click — its code, its history, its passwords — and the team keeps working with your laptop closed. 3. **Tell PA to release it.** “Put it on the test site.” “Release it to production.” PA hands it to the team’s build & deploy engineer. 4. **Every release can be put back.** Atlas marks the way back, the team backs up your data and proves the backup by restoring it, tries the database changes on that copy first, releases, and checks it is really live — [the same eight steps every time](https://bridge-terminal.com/atlas/#release). Your Claude, used well ### Your own Claude Code account. No API credits burned. 1. **Your Claude plan** · Pro or Max — the one you already pay for 2. **Claude Code, in the terminal** · signed in once with your account 3. **Every engineer is a session** · each with its own role and its own workspace 4. **Tuned per role** · the model and effort each job needs — your plan goes further No API keys to manage · No per-token API bill · Usage counts against your Claude plan Several engineers at once use a plan’s limits faster — Max gives the team the most room. Atlas’s price never includes Claude. Unattended, end to end ### Set the goal and walk away. Tested software comes back. No re-prompting stalled agents, no checking whether a test really ran. The team handles that — you get the decisions that are yours. Before you leave, just say the word You → PA · Run unattended and make decisions for me, don’t wait. PA → you · Understood. I’ll keep the team moving and make the routine calls myself, each one logged for you. [The five that are always yours](https://bridge-terminal.com/atlas/#never-decides) still wait for you, unless you say so and override it. Coming soon **Run unattended** One switch in Atlas will do the same — on when you leave, off when you’re back. An example night · on your company’s server 1. 19:04 · **Laptop closed** · the team carries on, on the server 2. 21:40 · **3 branches land** · one batch · your suite green 3. 23:15 · **A stall, picked up** · lease expired → task taken back 4. 01:30 · **Review: releasable** · 2 fixes filed to their builder 5. 04:50 · **Asleep** · the rest waits on one answer 6. 08:55 · **Your morning** · 1 question · 2 buttons · tested work #### Works with the laptop closed On your company’s server — overnight, at weekends. Sleeps when only you can unblock it. #### Stalls are caught Every task has an owner and a lease. Quiet work is picked up; a restart resumes. #### Done means done No “finished” without its tests, screenshots and your product’s rules passing. #### Tested together Work lands in batches through your own suite. A red batch is traced, never shipped. #### Reviewed twice Every build as it lands, and everything again before production. #### Asks only what’s yours One question, with buttons. Routine calls you’ve made the same way, it makes. **Always yours** Production go-lives · Spending money · Deleting real data · Sending to third parties · Dropping scope Daily budget · warns 50% · 80% · pauses 100% [The five it never decides →](https://bridge-terminal.com/atlas/#never-decides) The judgement layer ### Most AI tools execute. Atlas exercises judgement. It allocates thought by stakes, attacks its own big decisions before building them, earns the right to decide for you, and gets better with every project. It knows when to stop #### Five things it never decides for you However well it knows you. Everything else runs without interrupting you — routine work fast, irreversible or money-touching work with more thought. Production go-lives Spending money Deleting real data Sending to third parties Dropping scope you asked for It argues with itself #### Every big decision is attacked before it is built Three minds on one decision: one proposes, one tries to break it, one rules. You get the decision and its reasoning, on record. **Proposer** · commits to the best approach **Skeptic** · tries to break it **Judge** · rules, critique addressed ADR It earns autonomy #### It asks — until it has earned the right not to It learns from your answers, kind by kind. In unattended mode it decides a kind only once you have answered it the same way — every decision audited. The five above still always ask. It learns #### Every project makes the next one better Lessons from finished work reach future engineers — and are measured, not trusted. **Recorded** · from finished work, given to the next engineers **Controlled** · one lesson held back from each start **Retired** · every six hours, the ones tracking worse results or higher cost **Shared** · a lesson that recurs on two projects applies to all Evolve mode · only when you start it #### A product that improves itself, until you say stop 1. **Research** · the best in your category, the gaps nobody fills 2. **Propose** · a slate of improvements 3. **Build** · only what you approve 4. **Measure** · then round again Stopping never kills it: the cycle finishes cleanly, is tagged, and you get a report. A flaw Atlas finds in itself is fixed only with your approval. Testing ### Every case designed, run and proved — screenshots you can replay. From what you share, the code and your own lists — for systems Atlas builds and the ones you already have. Where test cases come from - **What you tell PA** · the goal, and the answers to its questions - **PRDs, specs and notes** · shared with PA — the more you share, the sharper the cases - **The code itself** · what Atlas built, or a system you already have - **Your own test cases** · a spreadsheet, Word or PDF you upload **The case library** steps · data · expected · tagged by technique · existing · gap · new - **Unit tests** - **Functional tests** · in a real browser - **Your list** · run on its own 1. **Designed** A test plan first — scenario, data, expected — tagged by technique. Risk · Partitions · Boundaries · Decision tables · States · Pairs · Error guessing 2. **Unit tests** Property-based first, then examples and edges. Test-first goals go red, then green. red → green · no weakening tests 3. **Functional tests** A real browser drives every screen, for every role, with a screenshot at each step. Playwright · console & network checked 4. **Landed** Your own suite runs on every batch. Production waits until everything passes. fresh test database · no faked AI calls Not only for what Atlas builds #### Existing systems too 1. **Reads your codebase** · maps every file, function and how they connect 2. **Works out what it is meant to do** · from the code, from what it knows of products like yours, and from any docs you share 3. **Sorts what is there** · tests that exist · behaviour no test covers yet 4. **Writes the missing cases** · unit and functional, then runs them Functional docs aren't required — they make the cases more solid. Bring your own test cases #### Match → fix → test 1. **Upload your list** · any sheet, Word or PDF — your column names 2. **Atlas checks the code against each case** · is it built? — with the files as evidence — and what your docs say _Example: three uploaded cases checked against the code_ 1. **Fixes what's missing, if you say so** · fix tasks go to the builders, one per gap 2. **Writes and runs your list** · then follow just your cases, on their own _An example of the Tests page: a run, a failing case explained, its screenshot and the step-by-step replay_ **Run all tests** — screenshots and a trace of every step **Upload your own list** — spreadsheet, Word or PDF; checked, then run **Ask in plain words** — add, change or remove cases **Where test time goes** — the slowest files, sped up on request **Download** — cases and runs as PDF or Excel Recordings ### No more issue lists. Talk it through, record, share. Walk through your app on a call, or record yourself showing what's wrong. Atlas lists every issue raised, each with a screenshot from the moment it was shown, and fixes them once a person approves. The old way 1. Type up each issue 2. Grab the screenshots 3. Paste them into a tracker 4. Explain it all again With Atlas Talk · Record · Share A client call, a walkthrough by your testers, or two minutes of you on your own. 1. **Record or upload** Start Atlas's recorder while you're on the call — Zoom, Meet, Teams, any app — or drop in a recording you already have. screen + voice · video · audio · transcript 2. **Issues listed** Transcribed on your own machine. Every issue raised is picked out, along with who it's for. issues · decisions · open questions 3. **Screenshots taken** From the moments the screen changes, or someone says “look at this”. Add your own from the replay. “see here” · screen changes · your picks 4. **A person approves** A quick review: edit the list, drop what isn't wanted, approve. Nothing is fixed before that. Approve and fix 5. **Fixed and tested** Each issue becomes a task on the board — a GitLab issue too, if connected — then built, tested and landed. tested before landing _An example of the Recordings screen: a walkthrough, the moments issues were raised, and the issues found with their screenshots_ Where it runs ### The same team on your Mac, or in your company's cloud. Start on your Mac. Move to your company's own server when the project grows — in one click, from the same app. #### On your Mac Available now - **One tab per project** — a team works while its tab is open - **Pauses with a fresh checkpoint** — closing the tab or quitting pauses it - **Opens paused after a restart** — nothing starts behind your back - **Sized to your Mac's memory** — how many engineers at once **One click** Settings → move to the server: code, history and passwords Atlas suggests it — once a day — when your Mac is what slows the team #### In your company's cloud Available now - **Your own account** — DigitalOcean today, signed in once; code and records stay there - **Laptop closed, team working** — each project sleeps after 30 idle, unwatched minutes - **A database per environment** — UAT, testing, production, when you say so - **A monthly budget cap** — warns at 80%, everything sleeps at 100% - **The setter-up's Claude account** — hand the project over and it's theirs **Awake** · someone has the project open, or the team is working Your cloud bill Awake · about $40 a month Asleep · about $5 + each project, only while it's awake The whole server sleeps when nothing runs — after 30 min · 1 h · 4 h · never, your choice — and wakes when someone opens a project. Why not just Claude Code? ### Claude Code is a superb engineer. Atlas is the team around it. Everything Atlas does runs on Claude Code sessions. It adds what a team adds around a good engineer — so good practice happens **every time, without anyone watching over it**. Claude Code on its own Drive every session · Read every terminal · Remember the order · Review when you can · **One session · and you, as the glue** · Merge, and fix main · Remember the backup · Start from nothing · Watch the money You carry everything around the session. With Atlas Specialists in parallel · A board that remembers · Gates and dependencies · “Done” enforced · **PA · one question at a time, to you** · Every build reviewed · The landing train · Eight-step releases · Lessons kept The team carries it — you answer PA. | What changes | Claude Code on its own | With Atlas | | --- | --- | --- | | Who you talk to | You drive every session and read every terminal. | **One PA.** Engineers escalate to it; you get one question at a time, with buttons. | | How many engineers | One session, or as many terminals as you can juggle. | **Specialists in parallel,** each its own Claude Code session — 26.1 h of work in 10.6 h on our own projects. | | What remembers the work | The session's context. Close the laptop or hit a crash and the thread is gone. | **A board in a database** — 45-minute leases, re-pings, checkpoints; a restart resumes. | | What "done" means | Done when the model says it is. | **Completion is refused** until it is on main, a screen has its cases and screenshots, and your rules pass. | | What waits for what | You remember the order and enforce it yourself. | **A dependency plan** — architecture, design and failing tests first; a screen waits for its API. | | Review | You review it, when you have time. | **Every build reviewed as it finishes** — releasable, or fixes filed to its builder. | | Getting onto main | You merge branches, and fix main when they collide. | **The landing train** — six at a time through your checks; a red batch is split, never shipped. | | Releasing | You remember to back up, test the database changes and keep a way back — or you don't. | **Eight steps every time** — way back marked, backup proven, changes rehearsed, checked. [How](https://bridge-terminal.com/atlas/#release) | | Getting better | Every session starts from nothing. | **Lessons passed on**, measured against a control, retired when they don't help. | | Money, secrets, the irreversible | Whatever the session is allowed to do. | **Never decided for you:** production go-lives, spending, deleting data, sending outside and dropping scope. A daily budget can pause at 100%; pasted secrets go to a secret store first. | | Evidence you can open | A terminal transcript. | **Screens built for proof** — Tests with replay, Security, Performance. | The team ### Every engineer owns a line, and the line ends in evidence. Each role is its own Claude Code session with a written job — what it does, hands over and must never do. Specialists beyond the standard roles are proposed by PA and approved by you. _The Atlas line map: goals leave the PA along six coloured lines — plan, build, prove, guard, ship and keep healthy — pass their checkpoints, meet at the gate where your checks run, and ride the landing train into main._ - **Plan** · architecture, research and design — building waits until the design is approved - **Build** · backend and screens, each on its own branch - **Prove** · tests, a real browser, and load against your targets - **Guard** · code review of every build, and security when you consent - **Ship** · the running app, and releases that can be put back - **Keep healthy** · documentation and dependencies #### PA, the one you talk to The interchange · every line starts here The single point of contact between you and every engineer. It routes, coordinates, escalates and reports — and never builds anything itself. ##### How it works 1. Works out whether you want to **discuss, plan or have something built**, and asks when it can't tell. You reach it in the app, by voice, or from Slack or Telegram. 2. Confirms the scope once, then lays the whole plan as **tasks that depend on each other**, API contracts first. 3. Sets goals with **measurable criteria** and opens the gates that apply: architecture, design, test-first. 4. Answers the engineers' questions, or brings them to you **one at a time, with buttons**. A burst of messages arrives as one. 5. Reports as it goes: milestones with their evidence, and **estimates only from the forecast**. **Hands over** · One message per reply, milestones with their evidence, and a message for each feature that reaches main. **Never** · Writes code. Approves production, spending, deleting data or a change of scope. Says "done" while a goal is below 100%. #### Architecture Plan line · the architecture gate System design and technical direction, written down before anything is built. ##### How it works 1. Holds **backend, UI and integration work** until the design is decided — the architecture gate. 2. Writes the design with **real choices and numbers**: topology, infrastructure, callers, cost, alternatives. 3. Picks the right diagram for each concern — component maps, request flows over time, the data model, state machines — and renders them into the document. 4. On an existing codebase, **maps it into the team's shared memory** before proposing anything. "Use real choices and numbers, not 'TBD'." **Hands over** · The design as a document with diagrams, for your approval. **Never** · Lets building start on a system decision you haven't reviewed. #### Research & gap analysis Plan line Finds the unknowns before they become rework. ##### How it works 1. Researches and **compares technologies**, with web access. 2. Measures the **gap between what is required and what is built**. 3. Runs **small proofs of concept** and surfaces the unknown unknowns. **Hands over** · Comparison tables and diagrams. Open research holds the release. #### UI design Plan line · the design gate The actual design — screens you can open and see, not a spec about the design. ##### How it works 1. Renders **every screen**, including its loading, empty and error states, with real tokens and realistic content. 2. Maps **every value on a screen to a real field** in the API. 3. Finishes **screen by screen**, so building can start on the first one. "A finished design task is not approval; the operator's sign-off is." **Hands over** · Mockups for your sign-off. Building waits until you give it. #### Backend development Build line The server side: APIs, the data model, the business logic. ##### How it works 1. Proposes the **API contract before implementing it**; changing an agreed shape is refused. 2. Reads the **project's code map** to know what a change will touch, instead of searching blind. 3. Proves each feature on **new inputs, one for every variant**. 4. Builds **against the failing tests** when the project works test-first. **Hands over** · Working code on its branch, reviewed the moment it finishes. **Never** · Weakens a test to make it pass. #### UI development Build line · checked against the design The real, running screen: the approved design, built faithfully, wired to live data. ##### How it works 1. Builds **every component the mockup shows**, with no hard-coded numbers or placeholder text. 2. Checks the agreed API shapes and **uses the generated types**. 3. Passes a **visual check** that scores the live screen against the design and catches reskins. "A reskin of the old screen is NOT a build." **Hands over** · A screenshot of the live screen. **Never** · Fakes data. A missing endpoint becomes a fix task for backend. #### Specialists Build line · made for your project Domain experts created for one project, with a set boundary, skills and a reason to exist. ##### How it works 1. Proposed by PA; **a new kind of role starts only with your approval** — the team grows only with your consent. 2. Writes the **contract first** and never weakens a test. 3. **Product plugins** (Salesforce, for example) bring their own specialists named for the roles your people recognise, and the platform's rules and gates — checked on every change. "Done means the REQUIREMENT works on real inputs." **Hands over** · The requirement working on real inputs. #### Testing Prove line · the test-first gate Owns the quality of the tests themselves. ##### How it works 1. Risk-ranks first, then walks the classic techniques — **equivalence classes, boundaries, decision tables, state transitions** — and tags every case with the technique that produced it. 2. Writes and shares the cases **before running anything**; property-based tests first where they fit. 3. Test-first: its failing tests turn the gate **red, which releases the builder**; green releases the release. 4. Grades its own tests with **mutation testing** — the number that says the assertions catch bugs. "Test the CAPABILITY, not the cache." **Hands over** · Cases and runs in the Tests screen. A claim without an artifact doesn't count. #### Browser QA Prove line · the end-to-end gate Proves the app works by driving it in a real browser against the running app. ##### How it works 1. Drives the **core user flows with new inputs**; any console or network error is a fail. 2. Writes specs for **every screen and every role**, unasked. 3. Backs up the design check **route by route**. "'Unit tests pass' is NOT your bar." **Hands over** · Runs with screenshots. Completion is refused without them. **Never** · Fixes the app. It verifies; the builders fix. #### Performance Prove line Answers whether the system takes the load you expect, and where it chokes first. ##### How it works 1. Turns the load model drafted from the code into **your terms**: orders per hour, people signed in. 2. Writes load scenarios: **a tenth of the load locally**, the full numbers on a server. 3. Reviews the code against the **published performance rule sets** that apply to the project. **Hands over** · Measurements against your targets, and the first bottleneck. **Never** · Points anything at production. #### Code review Guard line · on every build Quality, patterns and standards, on every build as it finishes. ##### How it works 1. Picks up the review Atlas **files automatically** for each finished build. 2. Treats **every rule line as blocking**, and files fixes to the builder by name. 3. Checks the designed feature is **really wired** — no silent downgrades, no falsely green tests. **Hands over** · Findings by file and line, and a verdict: RELEASABLE or not. Reviews hold the release, not the builder. #### Critic Guard line · when you want a second opinion An adversarial reviewer whose only job is to find what is wrong with plans and claims. ##### How it works 1. Checks a plan against the project's **constraints, goals, decisions and blockers**. 2. Names the **unstated assumptions** and the revisions the plan needs. 3. Scores honestly: **8 or more ships**, 5 to 7 is sent back to revise, 4 or less blocks. "You exist because Claude is congenitally agreeable." **Hands over** · A score out of 10 and a verdict: ship, revise or block. **Never** · Agrees out of politeness, or invents a flaw to seem useful. #### Security Guard line · with your consent Vulnerabilities, threat modelling and secure code — from a ledger rather than a hunch. ##### How it works 1. Works through **every module against 162 named attack classes** in 11 families. 2. Closes a unit **only with evidence**; a finding counts as fixed only after a re-test. 3. Asks before it runs: **now, at the next build, or hold** — and batches into one pass per build unless you say now. "'Looks fine' is not a result." **Hands over** · The coverage ledger and verified findings, in the Security screen. #### Build & deploy Ship line The running app — because a green test suite is not a running app. ##### How it works 1. Waits until **no build, review or fix is open**, and the train is idle. 2. Starts the frontend and API **on free ports** and hands the address to browser QA. 3. Treats a designed component that isn't attached as **a blocker**. Going live is always your decision. **Hands over** · The app running, and the deployment document updated. **Never** · Hand-fixes application code. #### The landing train Ship line · run by Atlas itself Not an engineer but the engine: it brings finished branches to main, tested together. ##### How it works 1. Merges **up to six finished branches** into one batch. 2. Runs **your project's own checks once** on the result. 3. Splits a red batch **until the branch that broke it is found**, and sends it back to its builder. 4. Main's history is **never rewritten**. **Hands over** · Work on main, and a message saying what arrived. #### Documentation Keep-healthy line Keeps the documents in step with the code. ##### How it works 1. **READMEs, API documents, the changelog** and decision records. 2. Runs **after testing and before the release**. 3. Renders documents **with their diagrams**, kept with a version history. **Hands over** · Documents in the app's Documentation tab. #### Dependency management Keep-healthy line Keeps the project's dependencies healthy. ##### How it works 1. Versions, outdated packages, and **the breaking changes that come with upgrades**. 2. **Licence compliance** and lock-file integrity. 3. Takes the dependency and vulnerability fixes the other engineers **route to it**. **Hands over** · Every package with its current version, the latest, any advisory, and the action. One goal, end to end ### What happens between "build me this" and main. The real sequence, as the engine runs it — the states are the ones on the board. 1. GOAL · **Intake** · PA confirms the scope once, with measurable criteria 2. PENDING · **Plan** · tasks that depend on each other; API contracts first 3. SCHEDULED · **Delivery** · due when its dependencies finish; gates checked 4. RUNNING · **Claim and work** · a 45-minute lease; checkpoints as it goes 5. RED → GREEN · **Tests** · test-first: failing tests release the builder 6. COMPLETED · **Complete, if it really is** · on main or queued; cases, screenshots, rules pass 7. RELEASABLE · **Review** · reviewed as it finishes, or fixes filed 8. ON MAIN · **Land** · the train brings it whole; browser QA drives it 9. MET · **You're told** · merged and tagged only if its suite is green Proof, not promises ### Evidence you can open. Each line ends in something you can open — a board, a test case, a ledger, a measurement, a map, a decision. #### Every task has an owner, a line and a state The board lives in a database, not in a conversation. Close the laptop, crash, restart: the tasks, their leases and the checkpoints are still there, and each engineer resumes where it stopped. - Dependencies, so a screen waits for the API it calls - Leases and re-pings, so nothing is quietly dropped - Every row links to its task, its owner and its evidence _Illustration of the board_ #### A reason for every case Each test case says what it did, what data it used, what it expected and what actually happened — evidence, not a pass/fail badge. Runs keep their screenshots and a step-by-step replay. - Cases tagged by the technique that produced them - Test-first goals go red, then green - Add or change cases by asking, in plain words _Illustration of the Tests screen_ #### Coverage, not a rubber stamp The Security screen leads with what has never been reviewed. Every module crossed with every attack class that applies, closed only with evidence; findings fixed only after a re-test. - 162 named attack classes, 11 families - Runs now, at the next build, or held — you choose - A clean result is a real result, recorded as one _Illustration of the security coverage ledger_ #### Load against your targets Performance turns a load model drafted from the code into your terms — orders an hour, people signed in — measures against your targets, and names the first thing to choke. - A tenth of the load on your Mac; the full numbers on a server - Never pointed at production _Illustration: response time rises with load and crosses the 300 millisecond target at about 160 people_ #### It maps the codebase before it changes it Every engineer reads the project's code map — files, functions and how they connect, clustered into communities — instead of searching blind. It is how a change knows what it will touch. - Kept current as the code changes - Existing projects are mapped on arrival _Illustration of the code map_ #### It watches the recording, not just the transcript Bring a recorded call. Atlas breaks the screen-share into scenes and reads what was on screen at each moment, so "this one" means the thing on the screen — then pulls out decisions, owners and action items as tracked work. _Illustration of a meeting summary_ #### Documents your team can approve Designs, decisions and reports arrive as rendered documents with diagrams and a version history. Where a document decides something, building waits for your approval. _Illustration of a document awaiting approval_ Illustrations with example data. In the app, these are your project's live screens. The landing train ### Finished work reaches main tested together. Branches that pass alone can still break each other. So Atlas lands them in batches, through your own checks, and never lets a red batch reach main. Waiting for finished branches… **Up to six at once** · Finished branches are merged into one batch, and your project's checks run once on the result. **Red is split, not shipped** · A failing batch is split until the branch that broke it is found; it goes back to its builder by name. **Main stays honest** · Main's history is never rewritten, and you get a message saying what arrived. Releasing ### Every release can be put back. Anywhere beyond your Mac, the same eight steps every time — and a release can't be called done without a record of each. 1. **Mark the way back** · the live version tagged; the previous release noted 2. **Back up the data** · restored into a scratch copy and counted, table by table 3. **Prove what ships** · the tests that ran on exactly this version, cited 4. **Rehearse the changes** · database changes run first on the restored copy 5. **Change the database** · in order — anything that deletes data waits for your yes 6. **Release** · exactly what was tested goes out 7. **Check it is really live** · new version answers, main flows work, counts match 8. **Put it back if not** · the previous version at once; data only with your yes What a release leaves behind, kept with the project (an example) - **rollback point** — release/production/before-2026-10-11 · previous deployment kept - **backup** — 578 MB · restored into a scratch copy · 33 tables, counts match - **tests** — this exact version, tested as it landed · full suite green - **rehearsal** — 4 database changes run on the restored copy · no rows lost - **migrations** — 4 applied in order · none deletes data - **release** — deployed - **verify** — passed · new version live · sign-in and checkout work - **way back** — redeploy the previous version · restore the backup only with your yes **15** · roles, each with its deliverable and the evidence it must produce **26.1 h** · of work in 10.6 h on the clock — specialists in parallel, on our own projects **162** · attack classes on the security coverage ledger **6** · finished branches per landing-train batch, tested together Coming soon · Plugins ### A team that already knows how your software is built. A plugin teaches the whole team how a platform — or your own product — is really built. The vendor's official docs, version by version · Your standards, decisions, linters and checks **Plugin** · every rule cites its source Your roles · Your rules, on every change · Hard stops — no one talks past them Platforms you build on #### Salesforce is built. More platforms after it. Made from the vendor's own documentation — accurate and current, never guessed. Your own software #### Atlas learns the product you already have A new feature reads as if the people who wrote the rest of it wrote it too. It speaks your roles #### The team becomes a Salesforce team Administrator, Apex Developer, LWC Developer — roles your people recognise. It catches the classics #### The mistakes that break production Queries in loops, hard-coded IDs, missing sharing rules — caught on every change. It won't ship below the bar #### Salesforce needs 75% test coverage. So does Atlas. The platform's release rules become a hard stop — for every engineer, every deadline. Plans ### One project in development free on your Mac. A licence for each on your server. Keep as many projects as you like. Every team gets 30 days free, including one project in development on its server. Free One on your Mac for everyone, with no limit on people - Your Atlas team works on one project at a time on your Mac - The whole team, every screen - Releases that can be put back, every time - Updates arrive by themselves [Download for Mac](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) Licences $50 / month for each project in development at the same time · 30 days free - Each project in development on your company's server needs one - On a Mac, one lets the team work on a second project at once - A paused project, or one asleep on the server, doesn't count - Your admin assigns them; a licence can move once a month [See pricing](https://bridge-terminal.com/atlas/pricing.html) Your organisation Your people formed by itself, from your email domain - Colleagues at your company's domain join it when they sign in - Whoever sets up its server becomes its admin, and everyone is told - The admin sees everyone, adds people and assigns licences - Freelancers on a personal address can be added too What “a project” means A project here means software your Atlas team is working on. What it produces — your app or website — is yours: it runs live on your own hosting, for as many users as you like, and Atlas never charges for that. A paused project, or one asleep on the server, costs nothing. #### Sign in with your email. No password. A six-digit code and a link arrive by email — either signs you in, on your Mac or your phone. New to Atlas? That is also how you sign up. After that it works offline for up to a week. #### Your code stays with you Atlas works on your Mac or in your own cloud account. Your code, your chat with PA and your documents are not sent to us. What Atlas's service does see is on the [Privacy](https://bridge-terminal.com/atlas/privacy.html) page. #### Updates by themselves Atlas shows what's new and updates with one click — now, tonight, or later. Your teams pause with their work saved, and resume after. Server updates are one click too, with everyone told first. #### Secrets stay secret Credentials pasted into chat go to the secret store before PA sees them, are handed to a tool only when it needs them, and are masked in every log and report. Bring the goal ### Set a goal. Watch a team build it. Atlas brings the team, the judgement, and the line to main. [Download for Mac](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) [Talk to us](mailto:atlas@bridge-terminal.com?subject=Atlas) For Macs with Apple silicon · one project free on your Mac · sign in with your email ## Related - [Atlas Pricing — Free on Your Mac, $50 per Project in Development](https://bridge-terminal.com/atlas/pricing.html) - [The Atlas blog](https://bridge-terminal.com/atlas/blog/) --- # Atlas Pricing — Free on Your Mac, $50 per Project in Development > Atlas pricing. One project in development is free on your Mac for ever; every team gets 30 days free with one project on its own server; after that a licence is $50 a month for each project in development at the same time. The software Atlas builds runs live at no charge, and Claude is billed separately by Anthropic. Canonical: https://bridge-terminal.com/atlas/pricing.html Last updated: 2026-10-26 Pricing ## Free on your Mac. $50 a month for each project in development beyond it. Keep as many projects as you like — you pay only for the ones your Atlas team is building at the same time. Every team gets 30 days, free, including one project in development on its own server, before deciding. [**You also need your own Claude account with Claude Code** (Claude Pro or Max). Atlas runs in Claude Code’s terminal mode on that plan — no API keys, no per-token API bill. Atlas’s price doesn’t include Claude.](https://bridge-terminal.com/atlas/#your-claude) Free $0 one project in development on your Mac, for ever - Your Atlas team works on one project at a time on your Mac - The whole team and every screen — nothing held back - As many people as you like, each with their own free project in development - Updates arrive by themselves [Download for Mac](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) Free trial 30 days from sign-up, once for each team - One project in development on your company's server included - The team keeps working with your laptop closed - No card needed — sign in with your email - When it ends, the server project pauses with its work saved [Start free](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) Licence $50 / month for each project in development at the same time - Each project in development on your company's server needs one - On a Mac, one lets the team work on a second project at once - A paused project, or one asleep on the server, doesn't count - Your admin assigns them; a licence can move once a month - Cancel any time · local tax added where it applies [Talk to us](mailto:atlas@bridge-terminal.com?subject=Atlas%20licences) What “a project” means A project here means software your Atlas team is working on. What it produces — your app or website — is yours: it runs live on your own hosting, for as many users as you like, and Atlas never charges for that. A paused project, or one asleep on the server, costs nothing. What it costs ### Counted by projects in development at the same time, not by people. A licence is for one project your Atlas team is working on at a time. Pause one and another can use it. The software you ship never counts. These are the common cases: | Your Atlas team is building | Per month | | --- | --- | | One project on your Mac | **$0** | | One project on your company's server, in your first 30 days | **$0** | | One project on your company's server, after the trial | **$50** | | Two projects on the server, plus each person's free Mac project | **$100** | | Two projects in development at once on one Mac | **$50** | | Ten projects on the server, the team working on one at a time | **$50** | Prices in US dollars, billed monthly. Local VAT, GST or sales tax is added at checkout where it applies. Atlas runs on your own Claude account and, for a server, your own DigitalOcean account — those are billed by them, not by Atlas. Questions ### Before you start #### What counts as a project? A project here means software your Atlas team is working on. What it produces — your app or website — is yours: it runs live on your own hosting, for as many users as you like, and Atlas never charges for that. A paused project, or one asleep on the server, costs nothing. You can keep as many projects as you like. #### What happens when the 30-day trial ends? Projects on your company's server pause with their work saved — nothing is deleted. Your project on your Mac stays free. Buy a licence and the server project starts again where it stopped. Atlas reminds you a week, three days and a day before the end. #### Do I need a card to start? No. Sign in with your email and the 30 days start. Nothing is charged until you buy a licence. #### Can I cancel? Yes, at any time. Your licences keep working until the end of the month you paid for, and you are not charged again. #### Can I get a refund? Yes. Ask within 14 days of a payment and it is refunded in full, to the way you paid. See the [refund policy](https://bridge-terminal.com/atlas/refunds.html). #### Who handles the payment? Lemon Squeezy, as the merchant of record: it takes the payment, adds local tax where it applies, and sends the invoice — in your company's name, with its tax number if you give one. Your card details never reach Atlas. #### Do I need my own Claude account? Yes. Atlas runs on Claude Code in the terminal, signed in with your own Claude plan (Pro or Max). Its engineers use that plan — not API keys, so there is no per-token API bill — and each role gets the model and effort its job needs, so the plan goes further. Several engineers at once use a plan’s limits faster; Max gives the team the most room. #### What else will I pay for? Atlas works through accounts you own: your Claude account and, for a server, your DigitalOcean account. Those are billed by Anthropic and DigitalOcean, not by Atlas, and Atlas shows what it spends. ### Start with one project on your Mac. It stays free. [Download for Mac](https://downloads.bridge-terminal.com/mac/Atlas-latest-arm64.dmg) For Macs with Apple silicon · sign in with your email · questions: [atlas@bridge-terminal.com](mailto:atlas@bridge-terminal.com) ## Related - [Atlas — an AI software team built on Claude Code](https://bridge-terminal.com/atlas/) - [Atlas Refund Policy](https://bridge-terminal.com/atlas/refunds.html) - [Atlas Terms](https://bridge-terminal.com/atlas/terms.html) --- # Atlas blog > The Atlas blog's index, newest first: what's new in AI coding tools such as Claude Code and Codex, plain-English guides for founders, product owners and testers, and how-tos for engineers. New articles arrive three times a day. Canonical: https://bridge-terminal.com/atlas/blog/ Last updated: 2026-10-26 Every article, newest first. Each has a Markdown copy at its address + `index.md`. Page 1 of 2. [Older](https://bridge-terminal.com/atlas/blog/page/2/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) — Claude Code mods are plugins that run code inside the tool itself. See what changed in October 2026, what mods can reach, and what a team should decide. (26 October 2026 · Plain English · What's new) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) — Set up Claude Code OpenTelemetry to stream token, cost and tool metrics to your own stack. Env vars, managed settings, privacy flags and queries to start. (25 October 2026 · Technical · From Atlas) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) — Why your AI coding agent stops mid-job on Claude Pro or Max, what the five-hour and weekly limits mean, and how to plan work so you are not stuck waiting. (25 October 2026 · Plain English · Explainer) - [Claude Fast Mode for Opus 5.5: Cost and When It Pays](https://bridge-terminal.com/atlas/blog/claude-fast-mode-opus-5-5-cost/) — Anthropic took Claude Opus 5.5 fast mode out of research preview on the API on 15 Oct 2026. What it costs and when a team should pay for the speed. (25 October 2026 · Plain English · What's new) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) — Which Claude Code settings file wins? The four scopes, precedence order, list merging, a team setup and fixes for settings that seem ignored. (24 October 2026 · Technical · How-to) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) — Repository, branch, pull request, context window, subagent: the words your AI coding agent keeps using, explained without code and with everyday examples. (24 October 2026 · Plain English · Explainer) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) — On 22 Oct 2026 Anthropic gave the Agent Skills standard to the Agentic AI Foundation. Here is what skills are and what the move means for your team. (24 October 2026 · Plain English · What's new) - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) — Package skills, subagents and hooks as a Claude Code plugin, host a team marketplace in git, and make every teammate get it. Commands and config included. (23 October 2026 · Technical · From Atlas) - [How to Run a First AI Coding Agent Pilot: A Plain Guide](https://bridge-terminal.com/atlas/blog/first-ai-coding-agent-pilot-plain-guide/) — Thinking of trying an AI coding agent? Pick the right first project, set a pass/fail test, cap the risk and decide after two weeks. A plain-English guide. (23 October 2026 · Plain English · How-to) - [Claude API Version 2026-10-21: What Teams Must Check](https://bridge-terminal.com/atlas/blog/claude-api-version-2026-10-21-what-to-check/) — Anthropic released Claude API version 2026-10-21 with breaking changes. Here is what changed, who is affected and what to ask your team to check first. (23 October 2026 · Plain English · What's new) - [Claude Code GitHub Actions: Set Up @claude on Your Repo](https://bridge-terminal.com/atlas/blog/claude-code-github-actions-setup-at-claude/) — Set up Claude Code GitHub Actions: install with /install-github-app, write the @claude workflow, run PR reviews and cron jobs, and cap cost and permissions. (22 October 2026 · Technical · How-to) - [Why AI Coding Agents Forget and How to Fix It](https://bridge-terminal.com/atlas/blog/why-ai-coding-agents-forget-project-memory/) — AI coding agents start every session blank and can lose early instructions mid-task. Here is why, and the plain-English fixes that make your rules stick. (22 October 2026 · Plain English · Explainer) - [Claude Code Safety Event: A Log of Every Blocked Action](https://bridge-terminal.com/atlas/blog/claude-code-safety-event-log-blocked-actions/) — Claude Code 2.1.307 adds a safety event that logs when a permission rule, auto mode, a safety check, a hook or the sandbox stops an action. What it means. (22 October 2026 · Plain English · What's new) - [Claude Code Sandbox: Limit Files and Network for Bash](https://bridge-terminal.com/atlas/blog/claude-code-sandbox-bash-files-network/) — Turn on Claude Code's built-in sandbox: set which files and hosts shell commands can reach, fix what breaks, and know what still runs outside it. (21 October 2026 · Technical · How-to) - [Your Role When AI Builds the Software: A Plain Guide](https://bridge-terminal.com/atlas/blog/your-role-when-ai-builds-your-software/) — What changes for founders, product owners and managers when AI agents write the code: you decide, define "done" and check evidence. A plain-English guide. (21 October 2026 · Plain English · Explainer) - [Claude Code Auto Mode Setup: Teach It Your Environment](https://bridge-terminal.com/atlas/blog/claude-code-auto-mode-setup-environment/) — Claude Code auto mode blocks what it doesn't know is yours. Since 19 Oct 2026, /auto-mode-setup works on more setups. What it does and what to check. (21 October 2026 · Plain English · What's new) - [Test-First with Claude Code: Failing Tests Before Code](https://bridge-terminal.com/atlas/blog/claude-code-test-first-workflow-failing-tests/) — Run test-first development with Claude Code: commit failing tests, block edits to them with a hook, finish on a /goal or Stop hook, then review in a fresh context. (20 October 2026 · Technical · How-to) - [How AI-Built Software Gets Released: A Plain Guide](https://bridge-terminal.com/atlas/blog/how-ai-built-software-gets-released-plain-guide/) — What happens between "the AI says it's done" and "customers can use it"? A plain guide to safe releases, with the questions to ask before you say go. (20 October 2026 · Plain English · Explainer) - [Claude Code Review Levels: Quick, Standard and Deep](https://bridge-terminal.com/atlas/blog/claude-code-review-levels-quick-standard-deep/) — Claude Code Review now has Quick, Standard and Deep levels and a switch for a whole GitHub organization. What changed on 19 Oct 2026 and what to check. (20 October 2026 · Plain English · What's new) - [AGENTS.md and CLAUDE.md: One Instruction File for Both](https://bridge-terminal.com/atlas/blog/agents-md-claude-md-one-instruction-file/) — Use one AGENTS.md for Claude Code and Codex: how each tool finds the file, the import and symlink options, size limits, and how to check what loaded. (19 October 2026 · Technical · How-to) - [What AI Coding Agents Can and Cannot Do: A Plain Guide](https://bridge-terminal.com/atlas/blog/what-ai-coding-agents-can-and-cannot-do/) — What can an AI coding agent do for your product, and where does it still need a person? A plain-English guide with everyday examples for non-coders. (19 October 2026 · Plain English · Explainer) - [Claude Code Hooks Can Now Fail Closed: What It Means](https://bridge-terminal.com/atlas/blog/claude-code-hooks-fail-closed-onfailure-block/) — Claude Code 2.1.295 lets a safety check block an action when the check itself breaks. Here is what changed, why it matters and what to ask your team. (19 October 2026 · Plain English · What's new) - [Claude Code Rewind: Undo AI Edits with Checkpoints](https://bridge-terminal.com/atlas/blog/claude-code-rewind-checkpoints-undo-edits/) — How Claude Code checkpoints and /rewind restore code, conversation or both, what they can't undo (Bash, most subagent edits), and how to pair them with git. (18 October 2026 · Technical · How-to) - [How Much Does an AI Coding Agent Cost? A Plain Guide](https://bridge-terminal.com/atlas/blog/how-much-does-ai-coding-agent-cost/) — What an AI coding agent costs: flat plans versus pay-per-use, Anthropic's published Claude Code averages, why bills climb, and habits that keep spending in check. (18 October 2026 · Plain English · Explainer) ## Related - [Atlas home](https://bridge-terminal.com/atlas/) - [RSS feed](https://bridge-terminal.com/atlas/blog/rss.xml) --- # Atlas blog — page 2 > The Atlas blog's index, newest first: what's new in AI coding tools such as Claude Code and Codex, plain-English guides for founders, product owners and testers, and how-tos for engineers. New articles arrive three times a day. Canonical: https://bridge-terminal.com/atlas/blog/page/2/ Last updated: 2026-10-22 Every article, newest first. Each has a Markdown copy at its address + `index.md`. Page 2 of 2. [Newer](https://bridge-terminal.com/atlas/blog/) - [Claude Code Forked Subagents Now On by Default](https://bridge-terminal.com/atlas/blog/claude-code-forked-subagents-default-on/) — Claude Code 2.1.302 (16 Oct 2026) turns on forked subagents in headless runs, the Agent SDK, desktop and VS Code. What a fork is and what to check. (18 October 2026 · Plain English · What's new) - [Claude Code Plan Mode and Verification Workflow](https://bridge-terminal.com/atlas/blog/claude-code-plan-mode-verify-workflow/) — A step-by-step Claude Code workflow: explore in plan mode, write a spec, give the agent a check it can run, then review in a fresh context before you commit. (17 October 2026 · Technical · How-to) - [AI Coding Agent Risks and How to Reduce Them](https://bridge-terminal.com/atlas/blog/ai-coding-agent-risks-what-can-go-wrong/) — Is an AI coding agent safe? A plain-English guide to what can go wrong, from deleted files to leaked passwords, and the simple controls that lower the risk. (17 October 2026 · Plain English · Explainer) - [Codex GPT-5.5 Retirement: What Your Team Should Check](https://bridge-terminal.com/atlas/blog/codex-gpt-5-5-retirement-what-to-check/) — OpenAI retired GPT-5.5 from Codex for ChatGPT sign-ins on 14 October 2026. Here is what changed, who is affected and what to check before work breaks. (17 October 2026 · Plain English · What's new) - [Claude Code Permissions: Allow, Deny Rules and Modes](https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/) — Set up Claude Code permissions that hold: how allow, ask and deny rules are ordered, which mode to pick, and the Bash rule traps that let commands slip through. (16 October 2026 · Technical · How-to) - [How to Brief an AI Coding Agent: A Plain-English Guide](https://bridge-terminal.com/atlas/blog/how-to-brief-ai-coding-agent-plain-english/) — How to brief an AI coding agent without writing code: what to put in the request, how to define "done", and the common mistakes that cost you rework. (16 October 2026 · Plain English · How-to) - [Claude Code Idle Compaction: Cheaper Breaks, Same Session](https://bridge-terminal.com/atlas/blog/claude-code-idle-compaction-prompt-cache/) — Claude Code 2.1.299 (14 Oct 2026) now compacts very long idle chats before the one-hour cache runs out. What changed, the trade-off, and how to turn it off. (16 October 2026 · Plain English · What's new) - [Claude Code Skills: Turn Repeated Prompts into Commands](https://bridge-terminal.com/atlas/blog/claude-code-skills-reusable-commands/) — Claude Code skills turn a checklist you keep pasting into a reusable /command. Covers SKILL.md, arguments, shell injection and tool permissions. (15 October 2026 · Technical · Explainer) - [How to Check AI-Built Software When You Don't Write Code](https://bridge-terminal.com/atlas/blog/check-ai-built-software-without-code/) — You can't read the code, but you can still tell whether an AI agent's work is good. Ask for evidence, set pass/fail checks, and try the edge cases yourself. (15 October 2026 · Plain English · How-to) - [Claude Haiku 5.5: What the Cheapest Claude Means for Teams](https://bridge-terminal.com/atlas/blog/claude-haiku-5-5-what-it-means-for-teams/) — Claude Haiku 5.5 arrived on 7 October 2026 with a 1M-token window at $0.10 per million input tokens. What it is good for, what it is not, and how to test it. (15 October 2026 · Plain English · What's new) - [MCP Servers in Claude Code: Connect Databases and Tools](https://bridge-terminal.com/atlas/blog/mcp-servers-claude-code-explained/) — How MCP servers work in Claude Code: add local and remote servers, choose a scope, handle OAuth and secrets, limit context use and lock them down for a team. (14 October 2026 · Technical · Explainer) - [Claude Code Costs: Cut Token Usage and Stretch Limits](https://bridge-terminal.com/atlas/blog/claude-code-costs-token-usage-limits/) — Where Claude Code spends tokens and how to cut it: /usage, model and effort choice, /clear vs /compact, prompt cache lifetime and team spend limits. (13 October 2026 · Technical · How-to) - [AI Code Review with Claude Code: What It Catches and Misses](https://bridge-terminal.com/atlas/blog/ai-code-review-claude-code-setup/) — Set up AI code review in Claude Code with /code-review, ultrareview, managed Code Review or GitHub Actions, and learn what it catches, misses and costs. (12 October 2026 · Technical · How-to) - [Claude Code Headless in CI: -p Mode and Safe Permissions](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/) — Run Claude Code headless in CI with claude -p: bare mode, dontAsk and allowedTools permissions, JSON output, exit codes and cost caps for unattended jobs. (11 October 2026 · Technical · How-to) - [Claude Code Subagents: When to Split Work and How](https://bridge-terminal.com/atlas/blog/claude-code-subagents-when-to-split-work/) — When Claude Code subagents help and when they don't: writing the agent file, choosing tools and models, and catching frontmatter mistakes that fail silently. (10 October 2026 · Technical · How-to) - [Claude Code Hooks as Guardrails: Block, Format, Test](https://bridge-terminal.com/atlas/blog/claude-code-hooks-guardrails/) — Use Claude Code hooks to block risky shell commands, protect files, format every edit and keep Claude working until tests pass, with configs you can copy. (9 October 2026 · Technical · How-to) - [Claude Code vs Codex for Teams: A Workflow Comparison](https://bridge-terminal.com/atlas/blog/claude-code-vs-codex-team-workflows/) — Claude Code vs OpenAI Codex for engineering teams: instruction files, permissions, hooks, CI, cloud tasks and PR review compared, and when to pick which tool. (8 October 2026 · Technical · Comparison) - [Codex CLI Setup: Install, Approval Modes and Sandboxing](https://bridge-terminal.com/atlas/blog/codex-cli-install-approval-modes-sandbox/) — Set up OpenAI Codex CLI: install it, sign in, write a config.toml and profile files, and choose the sandbox mode and approval policy for each kind of task. (7 October 2026 · Technical · How-to) - [CLAUDE.md Best Practices: What to Put in Your Project File](https://bridge-terminal.com/atlas/blog/claude-md-best-practices-project-instructions/) — What belongs in CLAUDE.md, what to cut, and when to use rules, imports, skills and hooks instead, based on Anthropic's Claude Code documentation. (6 October 2026 · Technical · How-to) - [Claude Code Worktrees: Run Parallel Sessions Safely](https://bridge-terminal.com/atlas/blog/claude-code-git-worktrees-parallel-sessions/) — How to run parallel Claude Code sessions with git worktrees: the --worktree flag, .worktreeinclude, subagent isolation, cleanup rules and merging back. (5 October 2026 · Technical · How-to) ## Related - [Atlas home](https://bridge-terminal.com/atlas/) - [RSS feed](https://bridge-terminal.com/atlas/blog/rss.xml) --- # Claude Code Mods: What They Are and the Risks to Check > Claude Code mods are plugins that run code inside the tool itself. See what changed in October 2026, what mods can reach, and what a team should decide. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/ Last updated: 2026-10-26 Published 26 October 2026 · Plain English · What's new · 7 min read ## The short version - A Claude Code mod is a plugin made of small programs that run inside Claude Code itself, so it can change how the tool looks and behaves, not just add instructions. - Mods run with the permissions of whoever installs them and are not sandboxed, so they need the same trust you would give any software installed on a work laptop. - Between 14 and 19 October 2026 Claude Code gained a hook for prompt-box changes (prompt.change) and an option that lets only a person approve a tool check (decider: "person"). - Administrators can keep user-installed mods out with the allowManagedModsOnly option on the built-in guard, and anyone can list what a mod does before installing it with claude plugin validate. - A non-engineer lead should ask one question now: who on the team may install mods, and who reviews them first? A mod in Claude Code is a plugin that runs small programs inside the tool itself, so it can change what Claude Code shows and does. Anthropic kept extending mods in October 2026. Because a mod acts with the permissions of the person who installs it, any team using Claude Code should decide who may install one. This article explains what mods are, what changed in the last two weeks, and what to settle before someone on your team adds one. ## What is a Claude Code mod? Anthropic's documentation describes a mod as a plugin that changes how Claude Code looks and behaves. A plugin is a bundle of add-ons for Claude Code. Other add-ons work from outside the tool: skills give Claude text instructions to read, and MCP servers (separate programs that give Claude extra tools) give it new tools to call. A mod is different. It is made of JavaScript or TypeScript event handlers, small pieces of code that Claude Code calls when something happens: a tool call, a submitted prompt, or part of the screen being drawn. For each event, a handler can do one of three things: - Watch it and let it continue unchanged. - Rewrite it before it continues. - Take it over and answer it, so the normal behaviour does not run. A refused command is an example. Anthropic shares three sample mods, with no support. One draws a forecast of your context window (the amount of text Claude can hold in mind at once) above the prompt. One holds a risky shell command, such as `rm -rf` or a force push, and shows what it would change, with buttons to proceed or cancel. One adds a `/replay` command that steps through the file edits Claude made in the last turn. Some of Claude Code's own features are mods too, including the `/diff` pane and the loading of AGENTS.md as project instructions. Mods work in the terminal, the Code tab of the Claude desktop app and the VS Code extension. Their handlers also run in `claude -p` (the mode used in automation) and the Agent SDK, but nothing is drawn there. ## What changed in the last two weeks? The Claude Code changelog shows mods getting more capable through October: - **14 October (version 2.1.300):** mods gained a `prompt.change` hook, which fires when the text in the prompt box changes without typing, for example when an earlier entry is recalled, the box is cleared or an edit is undone. The same release changed exit so that background commands still running 1.5 seconds after being asked to stop are force-killed. - **15 October (2.1.301):** a mod's text field can have several lines. - **19 October (2.1.304):** a mod's `tool.check` answer can carry `decider: "person"`. Then only the permission dialog, or a host program's callback, can approve the request, and it is refused with the mod's reason where nobody can be asked. - **VS Code:** the documentation says what a mod draws appears in the extension's chat panel from extension version 2.1.299, or 2.1.304 for sessions that do not fetch feature flags, such as those on Amazon Bedrock. Mods themselves arrived slightly earlier. The documentation says they are on by default in Claude Code 2.1.287 and later in the terminal, and from 2.1.286 in the desktop app. If your team updated Claude Code recently, mods are probably already switched on for you. ## Why should a non-engineer care? Because of one sentence in the documentation: a mod is "code that runs with your permissions." It can read and write any file your user account can reach, start programs and make network requests. Anthropic lists what a loaded mod can do: - Read secrets held in environment variables (named settings that programs inherit) and in settings files, including an API key. - See every prompt you send and every tool call Claude makes. - Rewrite a prompt or a tool call, submit a prompt as if you had typed it, or send a message to another of your sessions. - Approve a tool call before you are asked. - Spend your usage by calling a model on your plan or API key. Mods are not sandboxed. A sandbox is a walled-off area that limits what a program can touch. If you turn on Claude Code's sandboxing, it isolates the shell commands Claude runs, but a process that a mod starts runs outside it. None of this means mods are dangerous by nature. It means a mod is closer to installing an app than to adding a note to a prompt. The risk is the one you already manage with any software: where it came from and who vetted it. ## What protections already exist? Anthropic's guides describe several layers. **A built-in guard.** Claude Code loads a built-in mod called the guard ahead of every mod a user installs, when the machine has managed settings (settings an administrator deploys and users cannot change) or when the session uses a Team or Enterprise login. Users cannot turn it off. With the guard loaded, by default a user's mod cannot approve a call that a deny rule refuses, that an ask rule prompts for, or that a pre-tool-use hook blocked. A pre-tool-use hook is a script that runs before a tool does. **One option to keep users' mods out.** An administrator sets `allowManagedModsOnly` to true as an option on the guard, under `pluginConfigs` in managed settings. Then no mod a user brings runs its hooks, including one loaded from a folder with `--plugin-dir` or one that Claude wrote during a session. The organisation's own mods and the mods built into Claude Code still run. Users' ordinary settings hooks and status lines keep working. Because the guard reads the option from managed settings only, a user cannot undo it in their own files. **A way to look before installing.** Running `claude plugin validate` on a mod's folder lists, without running the mod, which events it handles (a `hooks:` line) and which actions it asks Claude Code to perform (a `calls:` line). Reading and writing files, starting programs, making network requests, reading environment variables and settings, and using your model plan each show up by name. Claude Code refuses to load a mod that uses its interface in a way this command cannot read. **A switch for a single session.** Starting Claude Code with `--safe-mode` turns off all installed mods, and also your other customisations, which helps when you suspect one caused a problem. Built-in mods stay on. There are limits. The guard's rules apply to Claude's own tool calls, not to a mod's own file and process calls. The documentation gives the example that with reading of `.env` denied, a mod can still read that file itself. To limit those, keep the mod from loading or write a policy mod of your own. ## What should a team decide this week? You do not need to write a mod to act on this. Four decisions are enough. 1. **Who may install mods?** If the answer is "anyone", say so on purpose. If the answer is "no one yet", ask whoever manages your settings about `allowManagedModsOnly`. 2. **Who reviews a mod first?** Make the `claude plugin validate` output part of the review. Anything that reads environment variables, starts programs or reaches the network deserves a human question about why. 3. **Where do secrets live?** A mod can read environment variables and settings files, so keep long-lived keys out of them where you can. 4. **Which updates reach people?** A mod is a plugin, so the controls for restricting which plugins users can install, and when a reviewed plugin may update, apply to mods too. For a pilot, the safe default is the plain one: start with no user-installed mods, and open the door for a named mod when someone can say what it does and who checked it. ## How does Atlas fit? Atlas is a team of AI engineers built on Claude Code, and each engineer is its own Claude Code session. Atlas's published feature list says nothing about showing or managing mods, so treat that as outside what it does today. The controls above are yours to set in Claude Code's own settings. Atlas is an independent product. You can see how the team works on the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Mods make Claude Code programmable from the inside, and Anthropic extended them again between 14 and 19 October 2026. The upside is real: custom panes, guards and commands. The cost is that each mod is trusted code. Decide who installs mods, review what they ask for before they load, and use the managed option if you want none from users at all. ## Questions people ask ### What is a Claude Code mod? A mod is a plugin made of JavaScript or TypeScript handlers that run inside Claude Code. A handler can watch, rewrite or take over events such as tool calls and prompts, and a mod can also draw its own panes and add commands. ### Are Claude Code mods safe to install? A mod runs with your permissions and is not sandboxed, so it can read files, start programs and make network requests. Install mods only from authors and marketplaces you trust, and run claude plugin validate on a mod's folder first to see which events it handles and what it calls. ### How do I turn mods off in Claude Code? Disable or uninstall one mod's plugin in /plugin, start Claude Code with --safe-mode for one session, or set disableAllHooks to true to stop every installed mod in every session (your settings hooks and custom status line stop too). An administrator can set allowManagedModsOnly to keep users' own mods from running. ### Are mods the same as hooks or skills? No. Settings hooks run a shell command, web request or prompt from outside Claude Code, and skills are instructions Claude reads. A mod is code that runs inside Claude Code, so it can also draw in the interface and rewrite events. ### Does Atlas manage Claude Code mods? Not today. Atlas's engineers are Claude Code sessions, and Atlas's published features do not cover showing or limiting mods. Set mod controls in Claude Code's own settings. ## About Atlas: Mods and the Atlas team: not covered yet Atlas runs each engineer as its own Claude Code session, but it does not yet show or control which mods those sessions load. Use Claude Code's managed settings and claude plugin validate to set those controls yourself. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code docs: Mods overview](https://code.claude.com/docs/en/plugins/mods/overview) - [Claude Code docs: Manage mods for your organization](https://code.claude.com/docs/en/plugins/mods/admin.md) - [Claude Code changelog](https://code.claude.com/docs/en/changelog) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) - [Claude Code Sandbox: Limit Files and Network for Bash](https://bridge-terminal.com/atlas/blog/claude-code-sandbox-bash-files-network/) - [Claude Code Permissions: Allow, Deny Rules and Modes](https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/) --- # Claude Code OpenTelemetry: Track Cost and Tool Use > Set up Claude Code OpenTelemetry to stream token, cost and tool metrics to your own stack. Env vars, managed settings, privacy flags and queries to start. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/ Last updated: 2026-10-25 Published 25 October 2026 · Technical · From Atlas · 7 min read ## The short version - Claude Code exports usage metrics and events through OpenTelemetry once you set CLAUDE_CODE_ENABLE_TELEMETRY=1 and choose an exporter. - 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. - Prompt text, tool details and raw API bodies are off by default, and each has its own opt-in flag. - Cost and token metrics can be split by model, subagent, skill, plugin and MCP server, which shows what drives your spend. - 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. To monitor Claude Code usage across a team, turn on its built-in OpenTelemetry export: set `CLAUDE_CODE_ENABLE_TELEMETRY=1`, 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. 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. ## Why export telemetry instead of reading /usage? `/usage` 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. 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. 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. ## How do I turn on Claude Code OpenTelemetry? Set environment variables before starting Claude Code. These are the documented basics: ```bash export CLAUDE_CODE_ENABLE_TELEMETRY=1 # required export OTEL_METRICS_EXPORTER=otlp # otlp, prometheus, console, none export OTEL_LOGS_EXPORTER=otlp # otlp, console, none export OTEL_EXPORTER_OTLP_PROTOCOL=grpc # grpc, http/json, http/protobuf export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token" ``` There is no default protocol, so set `OTEL_EXPORTER_OTLP_PROTOCOL` (or the per-signal protocol variable) for each OTLP exporter you enable. Metrics export every 60 seconds by default (`OTEL_METRIC_EXPORT_INTERVAL`, in milliseconds) and logs every 5 seconds (`OTEL_LOGS_EXPORT_INTERVAL`). ### Test locally first Before you involve a collector, print metrics to the terminal at a one-second interval: ```bash export CLAUDE_CODE_ENABLE_TELEMETRY=1 export OTEL_METRICS_EXPORTER=console export OTEL_METRIC_EXPORT_INTERVAL=1000 ``` Or expose a Prometheus endpoint and scrape `http://localhost:9464/metrics`: ```bash export CLAUDE_CODE_ENABLE_TELEMETRY=1 export OTEL_METRICS_EXPORTER=prometheus ``` To confirm a metrics pipeline works, look for `claude_code.session.count`, which is emitted at session start. For a logs-only setup, submit a prompt and look for the `claude_code.user_prompt` event. If nothing arrives, start Claude Code with `claude --debug-file ` and search the file for `[3P telemetry]` errors. Lines tagged `[Anthropic telemetry]` describe Anthropic's own operational telemetry and do not point to a problem with your setup. ### Send metrics and logs to different backends Per-signal variables override the generic ones: ```bash export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://metrics.example.com:4318 export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317 ``` Per-signal headers merge with the generic `OTEL_EXPORTER_OTLP_HEADERS`. Metric temporality defaults to `delta`; set `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=cumulative` if your backend expects that. ## How do I roll it out to a whole team? Put the variables in the managed settings file so they apply to every user: ```json { "env": { "CLAUDE_CODE_ENABLE_TELEMETRY": "1", "OTEL_METRICS_EXPORTER": "otlp", "OTEL_LOGS_EXPORTER": "otlp", "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc", "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317", "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token" } } ``` Four behaviours matter here, all from the docs: - Claude Code ignores `OTEL_*` exporter variables in `.claude/settings.json` and `.claude/settings.local.json`. A repository cannot enable telemetry, choose a destination or capture content. It can still set an exporter selector to `none` to turn a signal off, unless managed settings, a `--settings` file or the starting environment already sets that variable. - Setting `OTEL_EXPORTER_OTLP_ENDPOINT` 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. - The exporter selectors (`OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER`, `OTEL_TRACES_EXPORTER`) 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. - Claude Code does not pass `OTEL_*` variables to subprocesses such as the Bash tool, hooks, MCP servers or language servers, so your own scripts do not inherit your collector credentials. The first point is a useful safety property: a cloned repo cannot quietly redirect your telemetry. ## What does Claude Code measure? ### Metrics | Metric | What it counts | |---|---| | `claude_code.session.count` | Sessions, with `start_type`: `fresh`, `resume`, `continue`, `agents_view` | | `claude_code.lines_of_code.count` | Lines, `type` `added` or `removed` | | `claude_code.pull_request.count` | Pull requests | | `claude_code.commit.count` | Commits | | `claude_code.cost.usage` | Estimated USD cost, per API request | | `claude_code.token.usage` | Tokens by `type`: `input`, `output`, `cacheRead`, `cacheCreation` | | `claude_code.code_edit_tool.decision` | Accept or reject decisions for edit tools, with `tool_name`, `decision`, `source`, `language` | | `claude_code.active_time.total` | Seconds, split into `user` (keyboard) and `cli` (tools and responses) | Cost and token metrics also carry `model`, `query_source` (`main`, `subagent` or `auxiliary`), `speed`, `effort`, `agent.name`, `skill.name`, `plugin.name`, `mcp_server.name` and `mcp_tool.name`. 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. Agent, skill, plugin and MCP names are redacted to `custom` or `third-party` unless `OTEL_LOG_TOOL_DETAILS=1` is set. ### Events Events go through the logs exporter and share a `claude_code.` prefix. The useful ones: - `api_request`: model, `cost_usd`, `duration_ms`, token counts, `request_id`. - `api_error`: `error`, `status_code`, `attempt`. - `tool_result`: `tool_name`, `tool_use_id`, `success`, `duration_ms`, `decision_source`. - `tool_decision`: `decision` (`accept` or `reject`), `source`, `permission_mode`. - `user_prompt` and `assistant_response`: lengths by default, content only if you opt in. `prompt.id` links every event from one prompt. `event.sequence` is a per-process counter, so sort by `event.timestamp` first. With those you can reconstruct what one instruction cost and which tools it touched. ### Traces (beta) Set `CLAUDE_CODE_ENABLE_TELEMETRY=1` and `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`, then choose `OTEL_TRACES_EXPORTER`. Spans run from `claude_code.interaction`, the root span for each prompt, down to `claude_code.llm_request` and `claude_code.tool`, which has `blocked_on_user` and `execution` children. The blocked-on-user span shows how long work waited for a permission answer. The `claude_code.hook` span needs extra settings (`ENABLE_BETA_TRACING_DETAILED=1` and `BETA_TRACING_ENDPOINT`), and interactive CLI sessions also need organization allowlisting. ## What should I keep private? Content capture is off by default. Opt in deliberately: | Variable | Effect | |---|---| | `OTEL_LOG_USER_PROMPTS=1` | Prompt text in `user_prompt`; otherwise `` | | `OTEL_LOG_ASSISTANT_RESPONSES=1` | Response text; follows the prompts flag if unset, `0` keeps it redacted | | `OTEL_LOG_TOOL_DETAILS=1` | Tool parameters, Bash commands, MCP and skill names, full error messages | | `OTEL_LOG_TOOL_CONTENT=1` | Tool output in a span event (needs tracing) | | `OTEL_LOG_RAW_API_BODIES=1` or `file:` | Full API request and response bodies, inline or as untruncated files on disk | 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 (`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH`). 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. Standard attributes include `session.id`, `user.account_uuid`, `user.id` (a random anonymous ID) and `user.email`. If you do not want per-person data, check what your collector keeps. ## How do I keep metric cardinality under control? Every attribute multiplies series in your backend. Defaults: | Variable | Default | |---|---| | `OTEL_METRICS_INCLUDE_SESSION_ID` | `true` | | `OTEL_METRICS_INCLUDE_ACCOUNT_UUID` | `true` | | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | `true` | | `OTEL_METRICS_INCLUDE_VERSION` | `false` | | `OTEL_METRICS_INCLUDE_ENTRYPOINT` | `false` | | `OTEL_METRICS_INCLUDE_REPOSITORY` | `false` (v2.1.269 and later) | Session ID is the usual culprit, since every session creates a new series. If you only chart by team or model, set `OTEL_METRICS_INCLUDE_SESSION_ID=false`. To add your own dimensions, use `OTEL_RESOURCE_ATTRIBUTES`, for example `department=engineering,team.id=platform`. Values cannot contain spaces, and quotes do not escape them. ## What questions can the data answer? Start with four panels: 1. **Tokens by type over time.** A high `cacheCreation` share next to low `cacheRead` suggests sessions keep rebuilding context, for example after long idle gaps. 2. **Cost by `agent.name`, `skill.name` and `mcp_server.name`.** This shows whether a subagent or an MCP server dominates. Turn on `OTEL_LOG_TOOL_DETAILS=1` to see real names. 3. **`tool_decision` rejects and `blocked_on_user` time.** Many prompts waiting on a person point to permission rules that need tuning. 4. **`api_error` by `status_code`.** Rising errors or retries explain slow sessions better than guessing. Use the same data to check changes. If you move a task type to a smaller model or lower effort, compare `claude_code.cost.usage` split by `model` and `effort` before and after, rather than trusting a feeling. Where an organization pays contracted rates, the docs say cost figures, including OpenTelemetry, stay at list price unless an administrator sets the `modelPricing` managed setting (Claude Code v2.1.242 or later). That changes what is reported, not what is charged. ## Where does Atlas fit? 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. 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 [Atlas](https://bridge-terminal.com/atlas/). ## Conclusion 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. ## Questions people ask ### How do I enable OpenTelemetry in Claude Code? Set CLAUDE_CODE_ENABLE_TELEMETRY=1, choose exporters such as OTEL_METRICS_EXPORTER=otlp, and set OTEL_EXPORTER_OTLP_PROTOCOL (there is no default) and OTEL_EXPORTER_OTLP_ENDPOINT. To check it works, look for the claude_code.session.count metric. ### Can a repository turn on or redirect Claude Code telemetry? No. Claude Code ignores OTEL exporter variables in .claude/settings.json and .claude/settings.local.json. A repository can only set an exporter selector to none to turn a signal off, so rollouts belong in managed settings. ### Does Claude Code telemetry send my prompts? Not by default. Prompt text shows as unless you set OTEL_LOG_USER_PROMPTS=1, and tool details and raw API bodies have their own opt-in variables. ### Are the cost numbers in Claude Code telemetry my real bill? No. They are local estimates at list price unless an administrator sets the modelPricing managed setting, and even then they are not an invoice. On Pro and Max plans usage is included in the subscription, so the dollar figure is not a billing number. ### Can I break cost down by subagent, skill or MCP server? Yes. Cost and token metrics carry agent.name, skill.name, plugin.name and mcp_server.name attributes. The real names appear only when OTEL_LOG_TOOL_DETAILS=1 is set; otherwise they show as custom or third-party. ## About Atlas: Daily budget today, team telemetry export to come Atlas runs each engineer as a Claude Code session on your own Claude plan, with an optional daily budget that warns at 50% and 80% and pauses at 100%. Exporting team activity to your own collector is coming to Atlas, built in, so it needs no setup. Until then, use the settings in this article. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code OpenTelemetry reference (monitoring usage)](https://code.claude.com/docs/en/monitoring-usage) - [Manage costs effectively - Claude Code docs](https://code.claude.com/docs/en/costs) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) - [Claude Code GitHub Actions: Set Up @claude on Your Repo](https://bridge-terminal.com/atlas/blog/claude-code-github-actions-setup-at-claude/) --- # AI Coding Agent Usage Limits Explained in Plain English > Why your AI coding agent stops mid-job on Claude Pro or Max, what the five-hour and weekly limits mean, and how to plan work so you are not stuck waiting. Canonical: https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/ Last updated: 2026-10-25 Published 25 October 2026 · Plain English · Explainer · 6 min read ## The short version - 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. - 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. - Long conversations, bigger models, higher effort and many connected tools use the allowance faster, so short, focused sessions stretch it further. - Several AI engineers working at once use the plan faster, so size the plan to the amount of parallel work. - 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. 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. This guide explains those limits in plain English, what uses them up, and how a founder, product owner or manager can plan around them. ## What are AI coding agent usage limits? 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. 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.) ## Are chat and coding counted together? 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. 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. ## What happens when you hit the limit? 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. 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. 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. ## What uses up the allowance fastest? Anthropic points to these factors: - **Length and complexity of the conversation.** 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. - **The model you pick.** Model choice affects how quickly usage is consumed. - **The effort level.** Higher effort uses more tokens, so asking the agent to think hard on every small task adds up. - **Tools and connectors.** Anthropic describes these as token-intensive. 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. ## How can I make the allowance last longer? Anthropic's own tips are simple, and you can ask your team to follow them: 1. Start a new conversation when a long one nears your limit. 2. Use a lower effort level for routine work. 3. Turn off extended thinking when you do not need it. 4. Turn off connected apps and tools you are not using. 5. Remove unused project files and keep the project's instructions short. 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. ## Why do several AI engineers hit the limit sooner? 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. 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. ## What are my options when I hit the wall? Anthropic lists these choices: - **Wait for the reset.** Free, and fine if the work is not urgent. - **Upgrade your plan.** The new limits apply right away. - **Turn on usage credits.** Work carries on instead of stopping, but this is extra spending beyond your plan. Pro, Max and Team plans can buy them. - **Use a developer (Console) account with API credits.** Billed at standard API rates, which are separate from plan pricing. 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 `ANTHROPIC_API_KEY` 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 `/status` command, and that you can decline the API credit option when it is offered. ## How do I plan work around the limits? A few practical rules. They are our suggestions, not Anthropic's: - **Do the heavy work early in the week.** Save small fixes and polish for when the meter is low. - **Start big jobs at the beginning of a session.** Do not begin a large build when you are nearly out. - **Keep a buffer.** Do not run the plan to the limit in the middle of a release. A stop on release day is the worst time. - **Watch the trend.** If you reach the weekly limit early every week, either the work is too big for the plan or the sessions are too long. ## What Atlas does today 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. 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. 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 `/status`, and follow the planning rules above. ## Conclusion 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 [Atlas home page](https://bridge-terminal.com/atlas/) has more plain-language guides. ## Questions people ask ### What is the Claude Code five-hour limit? It is a session allowance on Claude Pro and Max plans that resets every five hours. There is also a weekly limit, and Claude chat and Claude Code share the same allowance. ### Do I lose my work when the agent hits a usage limit? No. Files already changed stay changed. The agent stops, or may be allowed to finish its current step, and you continue after the reset, an upgrade, or by turning on usage credits. ### Why does my AI coding agent run out of usage so quickly? Long conversations, bigger models, higher effort levels and many connected tools use more of the allowance. Chat use on the same account also counts, as does running several engineers at once. ### Does extra usage cost more? It is money on top of your plan. Anthropic says API credit usage is billed at standard API rates, separate from plan pricing, so decide who may turn it on. ### Can I set a stop before the plan runs out? Atlas has an optional daily budget that warns at 50% and 80% and pauses the team at 100%. A stop tied to the five-hour or weekly plan limits is coming to Atlas, built in. Until then, check /status. ## About Atlas: What Atlas does about usage limits today Atlas runs on your own Claude Pro or Max plan, so usage counts against it and several engineers at once use the limits faster. An optional daily budget warns at 50% and 80% and pauses at 100%. Stops tied to the plan's own limits are coming, built in. — https://bridge-terminal.com/atlas/ ## Sources - [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan) - [How do usage and length limits work?](https://support.claude.com/en/articles/11647753-how-do-usage-and-length-limits-work) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) - [How to Run a First AI Coding Agent Pilot: A Plain Guide](https://bridge-terminal.com/atlas/blog/first-ai-coding-agent-pilot-plain-guide/) --- # Claude Fast Mode for Opus 5.5: Cost and When It Pays > Anthropic took Claude Opus 5.5 fast mode out of research preview on the API on 15 Oct 2026. What it costs and when a team should pay for the speed. Canonical: https://bridge-terminal.com/atlas/blog/claude-fast-mode-opus-5-5-cost/ Last updated: 2026-10-25 Published 25 October 2026 · Plain English · What's new · 6 min read ## The short version - Fast mode runs the same Claude Opus 5.5 model with up to 2.5 times more output per second, at a higher price per token ($8 input, $40 output per million tokens). - On 15 October 2026 Anthropic took fast mode for Opus 5.5 out of research preview on the Claude API, so it needs no beta header or access request there. - In Claude Code on a Pro, Max, Team or Enterprise plan, fast mode is billed from usage credits, not from the plan's included usage. - Fast mode pays off when a person waits on the answer, such as live debugging, and rarely for long unattended tasks. - Atlas has no fast mode today; it is coming to Atlas, built in, with no setup. Atlas's engineers run on your Claude plan's usage meanwhile. Fast mode is a setting that makes Claude's Opus models write their answers up to 2.5 times faster, in return for a higher price per token. According to Anthropic's release notes, on 15 October 2026 fast mode for Claude Opus 5.5 came out of research preview on the Claude API. If your team uses an AI coding agent, the question is no longer "can we get it?" but "is the speed worth the money for this kind of work?" This article explains what changed, what fast mode costs, when it is worth paying for, and where Atlas stands on it. ## What is Claude fast mode? Fast mode is not a smarter or different model. Anthropic's documentation says it runs the same model with a faster setup behind the scenes, and that there is no change to intelligence or capabilities. What you get is speed in one specific place: output tokens per second, which is how fast the answer is written out. A token is a small chunk of text, roughly a word or part of one. Anthropic says the benefit is in output speed, not in the time to first token, so the first word does not appear sooner. A long answer simply finishes sooner. The figure is "up to" 2.5 times, not a promise for every request. ## What changed on 15 October 2026? Until then, fast mode on Anthropic's API was a research preview, meaning an unfinished feature that may change. You had to send a special beta header (a label attached to a request that marks it as using an unfinished feature) and ask for access. The Claude Platform release notes for 15 October 2026 say fast mode is out of research preview for Opus 5.5 and you no longer need to request access. The API documentation adds: - Opus 5.5 needs no beta header and no access request. Requests that still send the header keep working. - Opus 5.5 has a default fast mode rate limit on the Start, Build and Scale usage tiers, so most paying API accounts can use it straight away. - Fast mode on the older Opus 5 and Opus 4.8 stays in research preview and still needs the header. - The same day, fast mode for Opus 5.5 became available on Claude in Microsoft Foundry for deployments hosted on Azure. A 22 October entry says it is also available on Claude Models on Google Cloud (Anthropic managed). One detail to watch: when we read it on 25 October, the separate Claude Code documentation page for fast mode still carried a "research preview" note. So the label differs between the API pages and the Claude Code page. The prices below are the same on both. ## How much does fast mode cost? Anthropic prices fast mode per million tokens (MTok), counted separately for what goes in and what comes out: | Model | Input | Output | | - | - | - | | Claude Opus 5.5 | $8 per MTok | $40 per MTok | | Claude Opus 5 and Opus 4.8 | $10 per MTok | $50 per MTok | The price is the same across the whole context window, which is the amount of text the model can hold in mind at once. Other price modifiers, such as the discount for cached text, apply on top. There is one trap for people who switch it on mid-task. The Claude Code documentation says the first time you enable fast mode in a conversation, you pay the full fast mode price for the entire conversation so far. The deeper into a long session, the more that single switch costs. Turning it on at the start of a session keeps that charge smallest. The charge applies once per conversation, so toggling off and on again does not repeat it. ## How do you turn it on in Claude Code? In the Claude Code terminal tool, you type `/fast`, press Space to switch it on, and press Enter to confirm. A small ↯ icon next to the prompt shows that fast mode is active. Per the documentation, Opus 5.5 is the default fast mode model from Claude Code version 2.1.280 on. If your current model does not support fast mode, switching it on also moves you to Opus. The rules that matter to a business owner or manager are about who pays and who may switch it on: - On Pro, Max, Team and Enterprise plans, fast mode is available through usage credits only. It is not included in the subscription rate limits, and it draws from credits even when you still have plan usage left. On Team and Enterprise, the organization pays from its usage credits. - Usage credits must be turned on first. Until then, `/fast` reports "Fast mode requires usage credits". - On Team and Enterprise, fast mode is off by default. An Owner has to enable it for the organization. - Companies can set "per-session opt-in", so each session starts with fast mode off. Anthropic notes this is useful for controlling costs when people run several sessions at once. - Fast mode has its own rate limit. When you hit it, Claude Code drops back to standard speed and price, then switches fast mode back on when the cooldown ends. - Fast mode is not available through Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry or Claude Platform on AWS when used from Claude Code. On the API it does not work with the Batch API or with a Priority Tier commitment. ## When is fast mode worth paying for? Anthropic's own guidance is the clearest here. Fast mode suits interactive work where waiting hurts: - Rapid back-and-forth on code changes. - Live debugging. - Time-sensitive work against a deadline. Standard speed suits long autonomous tasks, batch processing, automated pipelines and cost-sensitive work better. If nobody is watching the screen, a faster answer saves nobody's time, and you still pay the higher rate. A simple test for a team: is a person sitting and waiting? If yes, a few minutes saved may be worth the extra tokens. If the agent is working through a long task overnight or in the background, leave it at standard speed. Fast mode is also not the only way to get quicker answers. Lowering the effort level makes the model think less, which is faster but may lower quality on complex tasks. Fast mode keeps the quality and trades money for speed. Anthropic says you can combine the two for maximum speed on straightforward tasks. ## What should a team do this week? 1. Decide who may use it. On Team or Enterprise, nothing happens until an Owner switches it on, so this is a deliberate choice. 2. Set a budget line for usage credits, since fast mode spends them directly. 3. Ask engineers to turn it on at the start of a session, not halfway through a long one. 4. Keep it for work where a person waits, and review the credit spend after a week. ## Does Atlas use fast mode? Not today. [Atlas](https://bridge-terminal.com/atlas/) is a software team made of AI engineers, built on Claude Code. Each engineer is its own Claude Code session with a written role, and its model and effort are tuned to that role. Atlas runs on your own Claude plan (Pro or Max), so usage counts against the plan, and it does not offer a fast mode switch. Fast mode is coming to Atlas, built in, so it will need no setup on your side. Until then, if you want fast mode for your own hands-on work, you can use `/fast` in Claude Code directly with usage credits turned on. Keep in mind that this spends credits outside the plan's included usage. Atlas also offers an optional daily budget that warns at 50% and 80% and pauses at 100%. ## Conclusion Fast mode is a straight trade: the same Opus 5.5 quality, up to 2.5 times quicker output, at $8 per million input tokens and $40 per million output tokens, billed from usage credits on subscription plans. The 15 October change mainly removes friction for API users. For teams, the real work is deciding when speed is worth the bill, and that usually means only when a person is waiting. ## Questions people ask ### What is fast mode in Claude? Fast mode runs the same Claude Opus model with a faster setup, giving up to 2.5 times more output tokens per second. It costs more per token and does not change the model's intelligence or capabilities. ### How much does Claude Opus 5.5 fast mode cost? Anthropic lists fast mode for Opus 5.5 at $8 per million input tokens and $40 per million output tokens. On Claude Code subscription plans it is billed from usage credits, not from the plan's included usage. ### Is fast mode out of research preview? For Claude Opus 5.5 on the Claude API, yes: Anthropic's release notes of 15 October 2026 say so, and no beta header or access request is needed. Opus 5 and Opus 4.8 remain in research preview, and the Claude Code docs page still showed a research preview note on 25 October. ### When should a team use fast mode? Use it when a person is waiting on the answer, such as live debugging or quick iteration. Anthropic suggests standard speed for long autonomous tasks, batch processing and cost-sensitive work. ### Does Atlas support fast mode? Not yet. Atlas runs its engineers on your own Claude plan, with model and effort tuned per role. Fast mode is coming to Atlas, built in, so it will need no setup. ## About Atlas: Fast mode and the Atlas team's plan usage Atlas engineers are Claude Code sessions that run on your own Claude plan, with model and effort tuned per role. Atlas has no fast mode switch today; it is coming to Atlas, built in, so it will need no setup. Until then, Atlas's optional daily budget warns at 50% and 80% and pauses the team at 100%. — https://bridge-terminal.com/atlas/ ## Sources - [Fast mode - Claude API docs](https://platform.claude.com/docs/en/build-with-claude/fast-mode) - [Speed up responses with fast mode - Claude Code docs](https://code.claude.com/docs/en/fast-mode) - [Claude Platform release notes, October 2026](https://platform.claude.com/docs/en/release-notes/overview) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude API Version 2026-10-21: What Teams Must Check](https://bridge-terminal.com/atlas/blog/claude-api-version-2026-10-21-what-to-check/) - [Claude Code Idle Compaction: Cheaper Breaks, Same Session](https://bridge-terminal.com/atlas/blog/claude-code-idle-compaction-prompt-cache/) - [Claude Haiku 5.5: What the Cheapest Claude Means for Teams](https://bridge-terminal.com/atlas/blog/claude-haiku-5-5-what-it-means-for-teams/) --- # Claude Code settings.json: Scopes and Precedence Explained > Which Claude Code settings file wins? The four scopes, precedence order, list merging, a team setup and fixes for settings that seem ignored. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/ Last updated: 2026-10-24 Published 24 October 2026 · Technical · How-to · 7 min read ## The short version - Claude Code reads settings from user, shared project, project local and managed scopes, and the file a key lives in decides who it applies to. - When a key is set in several places, managed settings win, then the --settings flag, then project local, shared project and user; list keys such as permissions.allow merge instead. - Commit .claude/settings.json for the team, keep personal overrides in .claude/settings.local.json, and run /status to confirm which files loaded. - A setting that seems ignored usually has a higher level overriding it, a value that is not allowed in project files, a folder not yet trusted, or a broken JSON file. - Settings files are strict JSON, so a comment or trailing comma breaks the file; claude doctor lists what Claude Code rejected. If you are asking which Claude Code settings file wins, the short answer is: managed settings first, then the `--settings` flag, then `.claude/settings.local.json`, then `.claude/settings.json`, then `~/.claude/settings.json`. List keys such as `permissions.allow` are the exception, because they merge across files. This article shows where each file lives, how to set up a shared team file with personal overrides, and how to debug a setting that does nothing. Everything here comes from the public Claude Code settings documentation. Version numbers quoted below are from that page; check your own version if a behaviour differs. ## What are the Claude Code settings files? Settings are JSON keys that control which model Claude Code starts with, what it may run without asking, which files it cannot read, and what your organization enforces. Claude Code reads four sources, and each has a scope: who the setting applies to. | Scope | File | Applies to | | :- | :- | :- | | User | `~/.claude/settings.json` | You, in every project on this machine | | Shared project | `.claude/settings.json` | Everyone who clones the repo, if you commit it | | Project local | `.claude/settings.local.json` | You, in this one project | | Managed | `managed-settings.json`, MDM policy or server-managed settings | Everyone your organization deploys it to | Installing Claude Code does not create any of these. Claude Code writes `~/.claude/settings.json` the first time you change a `/config` option that it stores in user settings, such as the theme, and `.claude/settings.local.json` the first time you give a standing approval on a permission prompt, such as "Yes, and don't ask again". There is also `~/.claude.json`, which Claude Code writes for itself (account details, MCP server configuration, trust decisions). You do not need to edit it. On Windows, `~/.claude` means `%USERPROFILE%\.claude`. Set `CLAUDE_CONFIG_DIR` to keep the home-directory files somewhere else. ## Which setting wins when a key appears twice? Claude Code uses the value from the highest level that sets the key. From highest to lowest: 1. Managed settings. Nothing in your own files or `--settings` overrides a managed key. 2. Command line: JSON passed with `--settings `, for that session only. 3. Project local: `.claude/settings.local.json`. 4. Shared project: `.claude/settings.json`. 5. User: `~/.claude/settings.json`. Environment variables are not a level in this stack. Whether a shell variable or a file wins is decided per pair. For example, `ANTHROPIC_MODEL` exported in your shell applies over the `model` key from any file, while `ANTHROPIC_DEFAULT_MODEL` applies only when no file sets `model`. ### Do lists override or merge? They merge. If `permissions.allow` appears in your user file and the project file, Claude Code combines both lists, so each file can add entries without removing another's. A few model-related keys follow their own rules. `fallbackModel` is taken whole from the highest file that defines it, because order carries meaning, and `modelPicker` is never merged across sources (it also needs v2.1.242 or later). This matters for permissions: an organization's allow rules still apply alongside yours unless it sets `allowManagedPermissionRulesOnly`. ## How do I set up a team file with personal overrides? Commit `.claude/settings.json` so everyone who clones the repository gets the same permissions, hooks and plugins. Each person overrides what they need in their own `.claude/settings.local.json`. A small shared file, assembled from rules in the documentation's examples: ```json { "$schema": "https://json.schemastore.org/claude-code-settings.json", "permissions": { "allow": [ "Bash(npm run lint)", "Bash(npm run test *)" ], "ask": [ "Bash(git push *)" ], "deny": [ "Read(./.env)", "Read(./.env.*)" ] } } ``` The `$schema` line gives autocomplete and validation in editors that support JSON schema. The documentation notes the schema can lag behind the newest CLI releases, so a warning on a recently documented key does not always mean your config is invalid. Settings files are strict JSON. A `//` comment or a trailing comma is a syntax error, and Claude Code reports a Settings Error at the next start. One caution from the example file: rules match the command as written. `Bash(git push *)` does not match `git -C . push`, and `Read(./.env)` alone does not stop a `grep -r` run over the directory. The documentation's team example adds a `sandbox` block to close that gap, because the sandbox adds your `Read` deny paths to what sandboxed commands cannot read. ### Personal override example If the team file sets a model and you prefer another, put your choice in the local file: ```json { "model": "claude-opus-5-5" } ``` Project local sits above shared project, so only your sessions change. Claude Code adds `**/.claude/settings.local.json` to your global git excludes the first time it writes the file. If you create the file by hand, add it to `.gitignore` yourself. Two details about where the local file lives. When you start Claude Code in a subdirectory of a git repository, it reads and writes the local file at the repository root (from v2.1.211; earlier versions kept it in the starting directory). In a worktree it uses the file at the main checkout's root. And Claude Code reads the shared file from the session's primary working directory, so start it at the repository root to pick up the committed file. ## How do I change a setting for one session only? Three ways, none of which write to a file: ```bash # pass any key a user settings file can set, inline or as a path claude --settings '{"model": "claude-opus-5-5"}' ``` You can also use a flag for that key, such as `--model` or `--effort`, or export the paired environment variable. `--settings` sits above user, project and local files but below managed settings, and it cannot set managed or global-config keys. Commands inside a session mostly save your choice. Changing a value in `/config` writes to your settings files, and `/model` saves the model as your default for new sessions. Pressing `s` in the `/model` picker switches the model without saving it. Each model has its own prompt cache, so the first request after a switch re-reads the whole conversation uncached. Claude Code watches the files and applies most edits, including `permissions` and `hooks`, to a running session without a restart. Some keys, `model` among them, are read only at session start; use `/model` or `/effort` to change those mid-session. ## Why is my setting being ignored? Start with `/status`. Its `Setting sources` line lists each file loaded for the session. It does not tell you which file supplied each key. Run `claude doctor` to list entries Claude Code rejected. Then check these causes: - **A higher level sets the same key.** A managed source, a `--settings` flag or the local file may override yours. A flag or environment variable can also override a key on its own. - **The value is not allowed in that file.** `permissions.defaultMode` values `auto` and `bypassPermissions` do not take effect from project or local settings. Set them in user or managed settings, or pass `--permission-mode` for one session. Telemetry export variables in an `env` block also do not apply from project or local files, apart from a few off values. - **The folder is not trusted yet.** `permissions.allow` rules, `permissions.additionalDirectories`, `extraKnownMarketplaces` and most `env` values from the committed file wait until each teammate trusts the folder. `deny` and `ask` rules apply immediately. Allow rules in an untracked local file do not wait for trust. - **The file is broken.** Invalid JSON gives a Settings Error dialog in an interactive session. A bad single entry, such as a malformed permission rule, gives a Settings Warning and Claude Code skips just that entry. In a `-p` run there is no dialog, so Claude Code skips the broken file or values without asking; run `claude doctor` afterwards. - **A "don't ask again" rule still prompts.** That choice saved an allow rule to your local file, and an allow rule there does not outrank an `ask` rule from a project or managed file. A few restrictive keys are honored from any scope even when managed settings say otherwise, for example `disableClaudeAiConnectors: true` and `permissions.blockReadsOutsideWorkingDirectories: true` (the latter needs v2.1.257 or later). So a project setting can make a session stricter than policy, never looser. ## Do settings apply in cloud sessions? Only partly. A cloud session runs on a fresh clone, so it reads the committed `.claude/settings.json` (for a single-repository session outside a project's threads) but not your user file or your local file. A `managed-settings.json` on your device does not reach it; server-managed settings do. Skills, plugins and CLAUDE.md follow their own rules, listed in the cloud environment docs. ## A sensible layout - User file: theme, editor mode, a default model, personal allow rules. - Shared project file: team allow and deny rules, hooks, the plugins and marketplaces the project needs. - Local file: experiments before you share them, and personal exceptions. - Instructions that are prose, not config, belong in a CLAUDE.md file rather than in settings. This article covers Claude Code itself. Atlas is an independent team of AI engineers built on Claude Code; it runs each engineer as its own Claude Code session. ## Conclusion Put each setting in the narrowest file that matches who it should affect: user for you everywhere, shared project for the team, local for you in one repo, managed for policy. Remember that lists merge, scalars follow the precedence stack, and some keys are refused in project files by design. When anything behaves oddly, `/status` and `claude doctor` are the first two things to run. ## Questions people ask ### Which Claude Code settings file takes precedence? Managed settings are highest, then the --settings flag, then .claude/settings.local.json, then .claude/settings.json, then ~/.claude/settings.json. List keys such as permissions.allow merge across files instead of overriding. ### Should I commit .claude/settings.json? Yes, if you want teammates to share permissions, hooks and plugins. Personal exceptions go in .claude/settings.local.json. Claude Code keeps that file out of git when it creates it; if you create it by hand, add it to .gitignore. ### How do I check which Claude Code settings loaded? Run /status and read the Setting sources line, which lists the files loaded. It does not show which file supplied each key. Run claude doctor to see entries Claude Code rejected. ### Why does my allow rule in the project settings not work? Allow rules in the committed project file apply only after each teammate trusts the folder. A higher level, such as a managed policy, or a broken JSON file can also override or skip it. ### Can I change a Claude Code setting for just one session? Yes. Pass JSON with --settings, use a key-specific flag such as --model, or export the paired environment variable. None of these write to your settings files. ## About Atlas: One Claude Code session per engineer Atlas is a team of AI engineers built on Claude Code, and each engineer is its own Claude Code session with a written role and its own working folder. Atlas is an independent product. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code: Settings files and precedence](https://code.claude.com/docs/en/settings) - [Claude Code: Example settings files](https://code.claude.com/docs/en/settings-example) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) - [Claude Code GitHub Actions: Set Up @claude on Your Repo](https://bridge-terminal.com/atlas/blog/claude-code-github-actions-setup-at-claude/) --- # AI Coding Agent Terms Explained in Plain English > Repository, branch, pull request, context window, subagent: the words your AI coding agent keeps using, explained without code and with everyday examples. Canonical: https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/ Last updated: 2026-10-24 Published 24 October 2026 · Plain English · Explainer · 7 min read ## The short version - Most AI coding jargon maps to something you already know: a shared folder, a copy to work on, a saved snapshot, a request for sign-off. - A repository is the project folder with its full history, a branch is a separate line of work, and a pull request is a proposal to merge that work back. - The context window is the agent's working memory; it fills up and early instructions can get lost, so lasting rules belong in a written instruction file, not in the chat. - Permission modes decide what the agent may do without asking, and undo covers file edits but not actions on databases, APIs or deployments. - You do not need to learn every term, but knowing the main ones helps you follow updates and spot a vague answer. If you work with an AI coding agent, you will hear words like repository, branch, pull request and context window. This guide explains the ones that matter in plain English, with everyday comparisons, so you can follow a status update and ask better questions. You do not need to use these words yourself, but knowing them makes it much harder for a vague answer to slip past you. The explanations follow how GitHub (a popular service for storing and reviewing software projects) and Claude Code (Anthropic's AI coding agent) describe things in their own documentation. Git is the standard tool for tracking changes to software, and GitHub's pages on it are the source for the first group of terms. ## Where the work lives ### What is a repository? A repository is the project's home. According to GitHub's documentation, it is the entire collection of files and folders for a project, along with each file's revision history. Think of a shared drive for one product, where every older version of every file is kept too. People often shorten it to "repo". When someone says "the agent has access to the repo", they mean it can read and change the project's files. ### What is a commit? A commit is a saved snapshot of the project at one moment. GitHub describes commits as snapshots in time that record the project's file history. Each one usually comes with a one-line note saying what changed. Why you care: commits are the receipts. If something breaks on Tuesday, the list of commits shows what changed on Monday and who or what changed it. ### What is a branch? A branch is a separate line of development. Commits can be arranged into several lines, and people use them to work on changes separately before combining them. Picture photocopying a contract to mark up your edits, rather than scribbling on the signed original. The original line is usually called "main". An agent can do its work on a branch so that a half-finished idea does not touch the version people rely on. Claude Code can also run several sessions at once by giving each its own directory for its own branch, so the sessions do not get in each other's way. ### What is a pull request? A pull request is a proposal to merge changes into the project. GitHub describes it as the place where people discuss and review changes before they are merged. It is the "please check this before it goes in" step. On a pull request, a reviewer can read the description and comments, see which lines changed, and look at the results of automated tests and builds. A pull request can also be opened as a draft, which is shared early and cannot be merged until it is marked ready for review. ### What does "merge" mean? Merging means folding the changes from a branch back into the main line. On a pull request, GitHub shows a merge status that lists blockers, missing approvals and other requirements. If your team has a rule such as "two approvals and passing tests", that is where it shows up. ## How the agent works ### What is an "agentic" tool? A plain chatbot answers with text. An agent can act. Claude Code's documentation says it works through three phases: gather context, take action and verify results. These blend together, and you can interrupt at any point. For a request like "fix the failing tests", the documentation describes the agent running the tests, reading the errors, finding the relevant files, editing them and running the tests again. It is closer to a junior colleague working through a checklist than to a search box. ### What is a tool, in this context? Tools are the things the agent can do: read and edit files, search, run commands, look things up on the web. The documentation puts it directly: without tools, Claude can only respond with text; with tools, it can act. This is why permissions matter. Every tool is something you may or may not want used unattended. ### What is a context window? The context window is the agent's working memory for the current conversation. Claude Code's documentation says it holds the conversation history, file contents, command outputs, instruction files, saved notes, loaded skills (reusable instructions for particular jobs) and system instructions. It fills up as you work. When it nears the limit, Claude Code clears older tool output first and then summarizes the conversation if needed. Your requests and key code snippets are kept, but the documentation warns that detailed instructions from early in the conversation may be lost. Everyday version: a whiteboard that is only so big. When it is full, someone wipes the old notes and keeps a summary. If a rule matters, do not leave it on the whiteboard. ### What is a session? A session is one conversation with the agent, tied to one project folder. The documentation states that each new session starts with a fresh context window, without the history of earlier ones. That is a common reason an agent can seem to "forget" yesterday's decision. ### What is an instruction file (CLAUDE.md or AGENTS.md)? It is a plain written document in the project that Claude Code reads at the start of every session. Teams use it for coding standards, architecture decisions and review checklists. If a project already has an AGENTS.md file written for other coding agents, Claude Code can read that instead. Think of it as the onboarding sheet a new hire gets on day one. If your rules live only in chat, they are not durable. ### What is a subagent? A subagent is a helper the main agent sends off to do part of a job. The documentation says it works in its own context window, its tool calls stay out of the main conversation, and the main agent gets back a summary when it finishes. It is like handing a colleague a sub-task so your own desk stays uncluttered. ### What is MCP? MCP, the Model Context Protocol, is described in the docs as an open standard for connecting AI tools to external data sources. With it, Claude Code can read design documents in Google Drive, update tickets in Jira or pull data from Slack. In plain terms: a plug that lets the agent reach your other tools. Each plug you add is also one more thing it can touch. ## Safety and control ### What is a permission mode? A permission mode sets what the agent may do without asking. The Claude Code documentation lists these: - **Auto:** a classifier reviews most actions in the background and blocks the risky ones instead of asking you. - **Manual:** Claude asks before file edits and shell commands. - **Accept edits:** Claude edits files and runs common file commands without asking, but still asks about other commands. - **Plan:** Claude explores and proposes a plan without editing your source files. The practical question for you: which mode is the team using, and who chose it? ### What is a checkpoint, and can I undo anything? Before Claude edits a file, it saves a snapshot of the contents. If something goes wrong, you can rewind. This only covers file changes. The documentation is explicit that actions affecting remote systems such as databases, APIs and deployments cannot be checkpointed. You control those with the permission mode and permission rules. So "we can undo it" is true for a bad edit to a page, and not automatically true for data deleted from a live database. Ask which kind of change you are talking about. ## Quality and release ### What are tests and checks? Tests are small automated programs that confirm the software still does what it should. "Checks" is the broader word for anything automated that runs on a change, such as tests or builds. On a pull request, GitHub shows their results in a Checks tab. A passing check is evidence, not proof: it only covers what someone wrote a test for. ### What is "production"? Production is the live version real customers use, as opposed to a copy used for trying things out. A release is the moment a change goes there. Because it affects real people and data, the go-ahead should come from a person. ## How Atlas fits in Atlas is a software team of AI engineers built on Claude Code. You talk to its project assistant, called PA, in plain words, so you can run a project without using most of these terms. Each engineer works in its own copy of the code, and tasks sit on a board where you can see them move. Finished work is merged by a step Atlas calls the landing train, which merges up to six finished branches and runs the project's own checks once on the result. Atlas does not yet explain terms such as branch, merge or checks where they appear on screen. Short plain-English explanations in the app are coming to Atlas, built in, so they will need no setup. Until then, ask PA to explain any word in plain terms. The Atlas home page is at [/atlas/](https://bridge-terminal.com/atlas/). ## A short conclusion Most of this vocabulary is ordinary project management dressed up: a shared folder, a working copy, a snapshot, a request for sign-off. If you remember only three ideas, make them these: work happens on a branch, not on the live version; the agent's memory is limited, so write down what matters; and undo has limits, so ask what is reversible before approving anything that touches live data. When an update uses a word you do not know, ask for the plain version. A good team can give you one. ## Questions people ask ### What is a repository in plain English? It is the project's home: all its files and folders plus the full history of changes to them. Think of a shared drive that remembers every older version. ### What is the difference between a branch and a pull request? A branch is a separate line of work where changes are made without touching the main version. A pull request is the proposal to merge that branch into the main project, where people review it first. ### What is a context window in an AI coding agent? It is the agent's working memory for the current conversation, holding the chat, file contents, command output and instruction files. It fills up, and detailed instructions from early on can be lost when older content is cleared or summarized. ### Can I undo what an AI coding agent did? In Claude Code, file edits can be rewound using saved snapshots. Actions on remote systems such as databases, APIs and deployments cannot be checkpointed, so those are controlled through the permission mode and permission rules. ### Do I need to learn these terms to use an AI coding agent? Not all of them. Knowing the main ones helps you follow updates and question vague answers. Tools that let you talk in plain words, and an agent you can ask to explain a term, reduce how much jargon you meet. ## About Atlas: Plain words in, the jargon handled for you With Atlas you brief PA, the project assistant, in plain words. Each AI engineer works in its own copy of the code, and a landing train merges finished branches and runs the project's checks. In-app explanations of terms are coming to Atlas, built in; until then, ask PA. — https://bridge-terminal.com/atlas/ ## Sources - [About Git - GitHub Docs](https://docs.github.com/en/get-started/using-git/about-git) - [About pull requests - GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) - [How Claude Code works - Claude Code Docs](https://code.claude.com/docs/en/how-claude-code-works) - [Claude Code overview](https://code.claude.com/docs/en/overview) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) - [How to Run a First AI Coding Agent Pilot: A Plain Guide](https://bridge-terminal.com/atlas/blog/first-ai-coding-agent-pilot-plain-guide/) --- # Agent Skills Now Belong to a Foundation: What It Means > On 22 Oct 2026 Anthropic gave the Agent Skills standard to the Agentic AI Foundation. Here is what skills are and what the move means for your team. Canonical: https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/ Last updated: 2026-10-24 Published 24 October 2026 · Plain English · What's new · 6 min read ## The short version - On 22 October 2026 Anthropic donated the Agent Skills standard, its name and logo, its GitHub organization and the agentskills.io domain to the Agentic AI Foundation, which is hosted by the Linux Foundation. - A skill is a package of written instructions that teaches an AI agent how to do one kind of task your way. Anthropic says more than 70 agent platforms have integrated the standard. - Nothing is required of current users: you can keep using skills as before and you do not have to join the foundation. - For a team, the practical gain is less lock-in: a skill written once is not tied to a single vendor's tool. - Anthropic has proposed versioned releases, a formal proposal process and security guidance for skills, but the announcement gives no dates for them. On 22 October 2026, Anthropic announced that it is giving Agent Skills, the open format for teaching AI agents how to do specific tasks, to the Agentic AI Foundation. If your team uses AI coding agents, the short answer is this: nothing breaks and nothing is required of you, but the format your team's know-how is written in now has a neutral home instead of a single company. This article explains what a skill is, what exactly changed on 22 October, what it means for a team building software, and where [Atlas](https://bridge-terminal.com/atlas/) stands on it today. ## What is an Agent Skill? A skill is a package of written instructions that teaches an AI agent how to do one kind of task the way your organisation does it. Think of the page in an employee handbook that says "this is how we prepare a release" or "this is how we write a customer report". The agent uses it when the task comes up and follows it. Anthropic says skills began with Claude Code, its AI coding tool. In its words, Claude Code "handled general knowledge work well, but often lacked the procedural knowledge that real business tasks need". Skills are meant to supply that missing know-how. Anthropic launched skills in October 2025 and published the format as an open standard in December 2025. "Open standard" here means the format is published for anyone to use, not locked to one product. ## What changed on 22 October 2026? According to Anthropic's announcement, it is donating four things to the Agentic AI Foundation (AAIF): - the standard itself; - the Agent Skills name and logo; - the GitHub organization where it lives (GitHub is the website where software projects are shared and worked on); - the agentskills.io website domain. The AAIF is hosted by the Linux Foundation, a long-standing non-profit home for shared software projects. Anthropic co-founded the AAIF last year with Block and OpenAI. Anthropic had already given it the Model Context Protocol (MCP), the standard for connecting agents to outside tools and data. In plain terms: until now, one company held the rulebook for skills. Now a neutral organisation does. ### Who will run it? The announcement says the standard will be maintained by engineers from Anthropic, Google, OpenAI and other companies, who take part as individuals. The two Lead Maintainers are David Soria Parra and Mahesh Murag. Joining the AAIF is not required to use the standard or to contribute to it. ### How widely is it used? Anthropic reports these figures in its announcement: - more than 70 agent platforms have integrated Agent Skills since the standard was published, including ChatGPT, Cursor, GitHub Copilot and VS Code; - 1 million skills have been published; - nearly 280 million skills have been installed. These are Anthropic's own numbers, so read them as the maker's claim. Anthropic also notes that within weeks of the October 2025 launch, developers had published thousands of skills and built loaders (small add-ons that let other tools read skills) for Codex, Cursor and OpenCode. ## Why does a neutral owner matter? Anthropic's stated aim is "to keep Agent Skills open, community-driven, and vendor-neutral". For a business, that translates into a few practical points. **Less lock-in.** Suppose your team writes a skill for how your company reviews contracts, or how your product's release notes should read. If one vendor controls the format, that work is a bet on that vendor. If many tools read the same format and a neutral body steers it, the bet is safer. You could change tools and keep the skill. **Clearer rules for change.** Anthropic has proposed a roadmap with three items: versioned releases, a formal proposal process for changes, and security guidance for people who write and install skills. The announcement gives no dates for any of them, so treat them as intentions, not commitments. Anthropic says the project will follow the same community-input and open decision-making approach used for MCP. **A clearer place to raise problems.** The specification is at agentskills.io, discussion happens on GitHub (github.com/agentskills/agentskills), and feedback on proposed changes to the specification goes through the project's Discord, a chat service. ## What does this mean for a team building software? For most teams, very little changes this week. Anthropic asks nothing of users beyond optional participation, and your existing skills keep working. The value is in the decisions you make from here. ### Treat skills as company assets A skill captures how your team likes work done. That is worth writing down properly, keeping a history of changes to, and reviewing, just as you would with code. Good first candidates are the things you keep explaining to new people: - how a bug report should be written and sorted by urgency; - your definition of "done" for a feature; - the checks every release must pass; - naming and style rules for documents or code. ### Take the security question seriously A skill is an instruction that an agent will follow. That means installing someone else's skill is a trust decision, a bit like running a stranger's checklist with your accounts open. Anthropic has put security guidance for writers and installers on its proposed roadmap, which suggests the topic is recognised. Until that guidance exists, the sensible habit is simple: read a skill before your team installs it, and prefer skills written in-house or by sources you trust. This is our advice, not something the announcement states. ### Do not expect it to fix quality by itself A skill can make an agent more consistent about the steps you describe. It does not prove that the work is correct. You still need tests, review and a person who checks the result. ## How does Atlas handle skills today? Honestly: Atlas does not yet let you add your own skills for its engineers to load. Atlas is a software team made of AI engineers, built on Claude Code. What it does today is teach its engineers through other routes. Domain plugins teach the team a product's rules, with Salesforce as one example, and those rules are checked against every change before work can be called done. Lessons from finished work are also passed on to future engineers. One lesson is held back as a control, and any lesson that tracks worse results or higher cost is retired automatically. Skills your team writes yourselves are not part of that yet. Support for them is coming to Atlas, built in, so it needs no setup on your side. Until then, put your standards into the brief you give PA, your project assistant, and let the checks on finished work show whether they are followed. ## What should you do this week? 1. Pick one repeated task and write down the steps in plain language. That draft is your first skill. 2. Ask your engineers which skills they already use, and where each came from. 3. Agree a simple rule for installing outside skills: someone reads it first. 4. Watch the Agent Skills discussion on GitHub for the versioning and security work Anthropic has proposed. ## Conclusion Moving Agent Skills to the Agentic AI Foundation is a governance change, not a feature change. It does not alter how skills work today, but it gives teams more reason to invest in them: Anthropic reports the format is integrated on more than 70 platforms, and it now has a neutral host. The sensible response is modest. Write down your team's best practices, treat outside skills with care, and keep your tests and reviews in place. ## Questions people ask ### What did Anthropic announce about Agent Skills on 22 October 2026? Anthropic said it is donating Agent Skills to the Agentic AI Foundation, which is hosted by the Linux Foundation. The gift includes the standard, the name and logo, the GitHub organization and the agentskills.io domain. ### What is an Agent Skill in simple terms? A skill is a package of written instructions that teaches an AI agent how to do one kind of task your way. The agent uses it when the task comes up and follows the steps. ### Do I have to do anything because of this change? No. Anthropic asks nothing of users beyond optional participation, and you do not need to join the foundation to use the standard or contribute to it. ### Which tools support Agent Skills? Anthropic says more than 70 agent platforms have integrated the standard, including ChatGPT, Cursor, GitHub Copilot and VS Code. That figure comes from Anthropic's own announcement. ### Does Atlas support Agent Skills? Not yet. Today Atlas teaches its engineers through domain plugins and lessons from finished work. Letting a team add its own skills is coming to Atlas, built in, with no setup. ## About Atlas: Skills are coming to Atlas; your standards count today Atlas does not yet load a team's own skills, but it already carries product rules through domain plugins and passes lessons from finished work to future engineers. Skill support is coming to Atlas, built in, so it needs no setup. Until then, put your standards in your briefs to PA. — https://bridge-terminal.com/atlas/ ## Sources - [Donating Agent Skills to the Agentic AI Foundation (Anthropic, 22 Oct 2026)](https://www.anthropic.com/news/donating-agent-skills-to-the-agentic-ai-foundation) - [Anthropic newsroom](https://www.anthropic.com/news) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [How to Run a First AI Coding Agent Pilot: A Plain Guide](https://bridge-terminal.com/atlas/blog/first-ai-coding-agent-pilot-plain-guide/) --- # Claude Code Plugins: Build a Team Marketplace > Package skills, subagents and hooks as a Claude Code plugin, host a team marketplace in git, and make every teammate get it. Commands and config included. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/ Last updated: 2026-10-23 Published 23 October 2026 · Technical · From Atlas · 7 min read ## The short version - A Claude Code plugin is one directory that bundles skills, subagents, hooks and MCP servers, with a small plugin.json manifest, so a team installs a whole setup as one unit. - Test a plugin with claude plugin validate and claude --plugin-dir before you publish anything; no marketplace is needed while you build. - A team marketplace is a git repository with a .claude-plugin/marketplace.json file; commit the project settings that --scope project writes and teammates get it once they trust the folder. - Set a version on every release or leave it out everywhere; if you set one and push without changing it, users keep their cached copy. - Every enabled plugin adds names and descriptions to each session's context, so keep the set small and check what each one costs. If your team keeps copying the same skills, subagents and hooks between repositories, a Claude Code plugin is the way to stop. A plugin is one directory that Claude Code installs and loads as a unit, and a marketplace is a git repository that lists plugins so teammates can install and update them by name. This guide builds a plugin, tests it locally, publishes it as a team marketplace and covers the settings that make it arrive on every machine. ## What is a Claude Code plugin? A plugin is a directory of skills, agents, hooks, MCP servers or other components, loaded as one unit. A JSON manifest at `.claude-plugin/plugin.json` gives it a name and optional metadata. Skills, agents, hooks and MCP servers all work on their own without a plugin, so you do not need one for a setup that serves one project or only you. Reach for a plugin when you want to share the setup with teammates, install it in several projects, or publish versioned releases. Plugin skills and agents get the plugin name as a prefix, such as `/my-plugin:hello`, so two plugins can each ship a `hello` skill without colliding. If you have not written skills and hooks yet, start with those; a plugin is how you ship them to others. ## How do I create a plugin? The layout is fixed. Only `plugin.json` goes inside `.claude-plugin/`; everything else sits at the plugin root. | Location | Contents | | :- | :- | | `.claude-plugin/plugin.json` | The manifest | | `skills/` | One `/SKILL.md` directory per skill | | `agents/` | One Markdown file per subagent | | `hooks/hooks.json` | Hook configuration | | `.mcp.json` | MCP server definitions | Components saved inside `.claude-plugin/` do not load. Create a minimal plugin: ```bash mkdir -p my-first-plugin/.claude-plugin mkdir -p my-first-plugin/skills/hello ``` ```json { "name": "my-first-plugin", "description": "A greeting plugin to learn the basics", "version": "1.0.0", "author": { "name": "Your Name" } } ``` Save that as `my-first-plugin/.claude-plugin/plugin.json`. Only `name` is required, and it must not contain spaces. Then add a skill at `my-first-plugin/skills/hello/SKILL.md`: ```markdown --- name: hello description: Greet the user with a friendly message disable-model-invocation: true --- Greet the user warmly and ask how you can help them today. ``` `disable-model-invocation: true` stops Claude from running the skill on its own, so you run it as `/my-first-plugin:hello`. Remove the line for a skill you want Claude to pick up by itself. ## How do I test a plugin before sharing it? You do not need a marketplace while you build. Validate first, then load the folder for one session: ```bash claude plugin validate ./my-first-plugin claude --plugin-dir ./my-first-plugin ``` Validation checks the manifest and the frontmatter of every skill, agent and command file, and exits `0` on `Validation passed`. Add `--strict` to fail on warnings too. Inside the session, `/reload-plugins` applies edits you made on disk. The `/plugin` Installed tab shows the components Claude Code found, and its Errors tab shows what failed to load. Two pitfalls. Pointing `--plugin-dir` at a marketplace root loads nothing and shows no error, because the flag wants one plugin's folder. And a plugin that loads cleanly can still fail to steer Claude the way you meant; `claude plugin eval` runs your test cases with and without the plugin and scores the difference. Other ways to load a plugin without installing it: `--plugin-url` takes a `.zip` from a URL (handy for a CI build artifact, and only for archives you control or trust), and the `CLAUDE_CODE_PLUGIN_DIRS` environment variable lists paths when you cannot add a flag. ## How do I move an existing .claude setup into a plugin? Copy the directories, then move the hooks. Run this from the project root: ```bash mkdir -p my-plugin/.claude-plugin cp -r .claude/skills my-plugin/ cp -r .claude/agents my-plugin/ mkdir -p my-plugin/hooks ``` Put a `plugin.json` in `my-plugin/.claude-plugin/`. Then create `my-plugin/hooks/hooks.json` with the `hooks` object copied from your settings file; the format is the same: ```json { "hooks": { "PostToolUse": [ { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npm run lint:fix" }] } ] } } ``` Load it with `claude --plugin-dir ./my-plugin` and check each piece under its new name, for example `/my-plugin:deploy` for a skill that was `/deploy`. While the originals remain under `.claude/`, skills and agents do not collide because of the prefix, but hooks have no prefix, so a hook in both places runs twice. Delete the originals once the plugin works. ## How do I set up a team marketplace? A marketplace is a directory or repository with `.claude-plugin/marketplace.json`. It requires a `name`, an `owner` and a `plugins` array, and each plugin entry needs a `name` and a `source`. ```bash mkdir -p my-marketplace/.claude-plugin my-marketplace/plugins cp -r my-first-plugin my-marketplace/plugins/ ``` ```json { "name": "my-marketplace", "description": "Plugins for my team", "owner": { "name": "Your Name" }, "plugins": [ { "name": "my-first-plugin", "source": "./plugins/my-first-plugin", "description": "A greeting plugin to learn the basics" } ] } ``` Write relative paths from the marketplace root, the directory that contains `.claude-plugin/`; paths with `..` fail validation. Keep the entry `name` the same as the `name` in the plugin's own manifest, or installs by manifest name report that the plugin is not found. Then validate, register and install locally: ```bash claude plugin validate ./my-marketplace claude plugin marketplace add ./my-marketplace claude plugin install my-first-plugin@my-marketplace claude plugin list ``` The install id is the entry name, an `@`, and the marketplace name. Because this local marketplace uses a relative path, edits show up at the next session start or `/reload-plugins`, with no version change. For plugins that live elsewhere, `source` can be an object: `{ "source": "github", "repo": "your-org/my-first-plugin" }`, or `git-subdir` for a folder inside a monorepo. Other source types are `url`, `archive` (a zip over HTTPS), `npm` and `command`. Pin a git-based source with `ref` or `sha`. ## How do teammates get the plugins? Push the marketplace to a git host. Teammates run `/plugin marketplace add your-org/your-marketplace` in a session, or `claude plugin marketplace add` in the shell. For hosts other than GitHub, send the full URL, since `owner/repo` shorthand always means github.com. To pin a branch or tag, append `#`. To avoid asking everyone to run commands, register the marketplace for the repository. Run this once in the repo and commit the `.claude/settings.json` it writes: ```bash claude plugin marketplace add your-org/your-marketplace --scope project ``` Claude Code then registers the marketplace for each teammate who trusts the folder. In an untrusted folder it ignores the entries without a message. If a plugin's marketplace entry points to an external source, such as its own GitHub repository, each contributor sees that it is enabled in project settings but not installed, until they run `claude plugin install @ --scope project`. Plugins listed by relative path load from the marketplace copy. You can enable plugins in the same settings file with `enabledPlugins`, using `plugin-name@marketplace-name` keys. Organizations can force this through managed settings with `extraKnownMarketplaces` and `enabledPlugins`, and managed settings take precedence over every other scope. In `claude -p` and CI runs, plugins install in the background, so one can be missing from the first turn. Set `CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1` to make the run wait. For private marketplaces, Claude Code has no git token of its own; it runs git on the machine with prompts turned off and relies on credentials already stored there. On GitHub Actions, export a token with read access as `GH_TOKEN` and run `gh auth setup-git`. ## How do versions and updates work? Users get a new copy of a plugin only when its computed version changes. You have two safe choices: - Bump `version` on every release. If you set `"1.0.0"` and push new commits without changing it, users keep the cached copy. - Omit `version` everywhere, and users track your commits. Do not set `version` in both `plugin.json` and the marketplace entry; Claude Code silently uses the `plugin.json` value and validation reports the mismatch. Background auto-update is off by default and `marketplace.json` has no field to turn it on. Each user enables it under Marketplaces in `/plugin`, or an admin sets `"autoUpdate": true` on the managed marketplace entry. Without it, users run `/plugin marketplace update ` or `claude plugin update @`. To change the label users see without breaking installs, set `displayName` in `plugin.json`. If you must change the plugin's `name`, add a top-level `renames` map to `marketplace.json` so existing installs migrate; `null` marks a removed plugin: ```json { "renames": { "formatter": "code-formatter", "legacy-linter": null } } ``` ## What does a plugin cost and what can go wrong? An enabled plugin is part of every session. The name and description of each skill, agent and command Claude can invoke on its own sit in context on every turn, which counts toward usage even when nothing from the plugin runs. Its MCP servers run alongside the session and its hooks fire at their events. Disable one without uninstalling with `claude plugin disable`. Security matters as much. What a plugin runs, it runs as you, and a third-party marketplace is any one other than Anthropic's. Read a plugin's hooks and MCP config before installing. Administrators can restrict sources with `strictKnownMarketplaces`, block plugins by setting them to `false` in managed `enabledPlugins`, and reject `--plugin-dir` and `--plugin-url` with `disableSideloadFlags`. ## Where Atlas fits Atlas is a team of AI engineers built on Claude Code. It has its own domain plugins, which teach the team a product's rules: the plugin's personas rename the roles, and its rules are checked against every change before work counts as done. Salesforce is one example. Installing Claude Code plugins from a team marketplace, as described above, is not something Atlas does today. That is coming to Atlas, built in, so it will need no setup on your side. Until then, install your plugins in Claude Code yourself. Learn more at the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Start with one plugin that holds the skills and hooks your team already copies around, validate it, and test it with `--plugin-dir`. Put it in a small git marketplace, commit the project-scoped registration, and decide up front whether you bump `version` or omit it. Keep the enabled set small, since each plugin adds to every session. ## Questions people ask ### What is a Claude Code plugin? A plugin is a directory of skills, agents, hooks, MCP servers or other components, with a plugin.json manifest, that Claude Code installs and loads as one unit. Use one when you want to share a setup with teammates or install it in several projects. ### How do I test a Claude Code plugin locally? Run claude plugin validate on the folder, then start a session with claude --plugin-dir pointing at it. Use /reload-plugins after edits and check the Errors tab in /plugin if something does not load. ### How do I share a plugin marketplace with my team? Push a repository containing .claude-plugin/marketplace.json to a git host and have teammates run /plugin marketplace add. To cover a whole repository, add it with --scope project and commit the .claude/settings.json it writes. ### Why are my plugin updates not reaching users? Users get a new copy only when the plugin's version changes. If you set a version and push commits without bumping it, they keep the cached copy; omit the version everywhere to track commits instead. ### Do plugins increase token usage? Yes. Names and descriptions of skills, agents and commands Claude can invoke on its own are in context on every turn, even when the plugin is not used, so keep the enabled set small. ## About Atlas: Plugins that teach a team a product's rules Atlas has domain plugins that teach its AI engineers a product's rules, with Salesforce as one example, and it checks those rules against every change before work counts as done. Installing Claude Code plugins from a team marketplace is not something Atlas does today; that is coming to Atlas, built in, so it needs no setup. Until then, install your plugins in Claude Code yourself. — https://bridge-terminal.com/atlas/ ## Sources - [Plugins overview - Claude Code Docs](https://code.claude.com/docs/en/plugins) - [Create a Claude Code plugin](https://code.claude.com/docs/en/plugins/create.md) - [Create a marketplace](https://code.claude.com/docs/en/plugin-marketplaces) - [Host and maintain a marketplace](https://code.claude.com/docs/en/plugins/host-marketplace.md) - [Manage Claude Code plugins for your organization](https://code.claude.com/docs/en/plugins/org.md) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) --- # How to Run a First AI Coding Agent Pilot: A Plain Guide > Thinking of trying an AI coding agent? Pick the right first project, set a pass/fail test, cap the risk and decide after two weeks. A plain-English guide. Canonical: https://bridge-terminal.com/atlas/blog/first-ai-coding-agent-pilot-plain-guide/ Last updated: 2026-10-23 Published 23 October 2026 · Plain English · How-to · 7 min read ## The short version - Run your first AI coding agent project as a small, time-boxed pilot with a written pass/fail test, not as a company-wide bet. - Pick a first task that is useful but low-stakes, easy to describe and easy to check, such as an internal tool or a small improvement to an existing product. - Write down before you start what 'done' looks like as checks the agent can run, because an agent stops when the work merely looks finished. - Keep the risk small: use test data instead of real data, and keep a person in charge of anything that goes live, spends money or deletes things. - At the end, judge the pilot on working software you could verify, your own time spent, and what it cost, then decide to stop, repeat or widen it. If you are deciding whether to try an AI coding agent, do not start with your most important product. Start with a small pilot: one real but low-stakes task, a clear test for "done", a fixed time box of about two weeks, and a decision at the end. That gives you evidence from your own work instead of someone else's demo. This guide is for people who do not write code: founders, product owners, analysts, testers, managers and agency owners. It walks through how to choose the first project, how to brief it, how to keep the risk low and how to judge the result. ## What is an AI coding agent pilot? An AI coding agent is a program that does more than answer questions. Anthropic's documentation says Claude Code can read your files, run commands, make changes and work through problems on its own while you watch, redirect or step away. A pilot is a deliberately small trial of that. You are not buying a result yet. You are finding out three things: - Can it produce work you can verify? - How much of your own time does it need? - What does it cost, and is the cost predictable? Treat it like trying a new contractor on a small job before giving them a big one. ## How do I pick the first project? The best first project sits in the middle. It should matter enough that you care about the result, and be small enough that a bad result costs you little. Good first projects: - **An internal tool.** A page that turns a spreadsheet into a weekly report, or a small form that replaces an email chain. Only your own staff use it, so mistakes are cheap. - **A small improvement to something that exists.** A new field on a form, a clearer error message, a filter on a list. - **Tests for something that has none.** Anthropic lists writing tests for untested code among the tedious tasks Claude Code takes on. It is also a fairly safe task, because tests do not change what your customers see. - **A prototype you will throw away.** The point is to learn what you want, not to ship. Poor first projects: - Anything that handles payments, sign-in or personal data on day one. - A rewrite of your core product. - Anything where you cannot say in two sentences what "finished" means. A useful rule from the documentation: if you could describe the change in one sentence, it is small enough to just ask for. If you are unsure of the approach, or the change touches many files, a planning step first is worth the overhead. ## How do I write down what "done" means? This is the most important step, and it is the one most people skip. Anthropic's best-practice guide says Claude "stops when the work looks done". Without a check it can run, "looks done" is the only signal it has, and you become the person who has to notice every mistake. Give it something that returns pass or fail and it can do the work, run the check, read the result and try again by itself. You do not need to write the checks yourself. You need to state the outcomes in plain words: - "A customer who enters an invalid email sees a message and cannot continue." - "The weekly report totals match this spreadsheet to the cent." - "The new page looks like this screenshot." Each of those can become an automatic test (a small script that reports pass or fail) or a screenshot comparison. The documentation's own example does this for an email check: it lists a few addresses that should pass and a few that should fail, and asks the agent to run the tests after building. Ask for evidence, not assurances. The guide suggests having the agent show the test output, the command it ran and what came back, or a screenshot of the result. ## Should the agent ask me questions first? For anything bigger than a tweak, yes. The documentation suggests letting the agent interview you before it builds. It asks about technical choices, screens, edge cases (unusual situations) and trade-offs you may not have considered, then writes a specification. The guide says time spent making the spec precise pays off more than time spent watching the work. For a non-coder this is a gift. Answering questions in your own words is easier than writing requirements from nothing, and you get a written document you can read, correct and keep. The same guide recommends separating planning from building: let the agent read and propose a plan first, with no changes made, and approve it before it starts. Read the plan the way you would read a quote. ## How do I keep the risk low? Pilots go wrong when they are trusted too early. A few simple rules cover most of the risk. 1. **Use copies, not the real thing.** Give the agent test data, not your live customer list. 2. **Keep a person in charge of the irreversible.** Putting something live, spending money, deleting data and sending messages outside the company should wait for a human yes. 3. **Keep a way back.** The documentation says every prompt you send that starts a turn creates a checkpoint, a saved point you can rewind to. But checkpoints only track changes made through the agent's file editing. Changes made by other commands are not captured, and the documentation says checkpoints are not a replacement for git, the standard tool for keeping a project's version history. Keep normal backups too. 4. **Do not ship what you cannot verify.** The documentation names a failure pattern: the agent produces a plausible-looking result that does not handle edge cases. Its fix: always provide verification, and if you cannot verify it, do not ship it. 5. **Get a second pair of eyes.** The guide notes that a reviewer starting from a fresh context is not biased toward code it just wrote, so it recommends a separate reviewer for important work. The agent that wrote something is not the best judge of it. ## What will it cost, and how much of my time? Two costs matter: the tool's cost and your attention. The tool's cost depends on how you pay. Claude Code can be used with a Claude subscription or with an Anthropic Console account, and the two bill differently. Check your own plan's limits before you start. For a pilot, decide a ceiling in advance and look at the usage after the first few days, not at the end. Your attention is the cost people forget. Expect to spend time on three things: answering the agent's questions, reading the plan, and checking the result. If a pilot "works" but needs you for four hours a day, that is information too. One practical habit from the documentation saves both time and money. If you have corrected the agent more than twice on the same issue in one session (one running conversation), stop. The conversation is now cluttered with failed attempts. Clear it and start fresh with a more specific brief that includes what you learned. The guide says a clean session with a better prompt almost always does better than a long one full of corrections. ## How do I judge the pilot? Before you start, write down your yardstick. At the end of two weeks, ask: - **Did it work?** Does the software do what you listed under "done", and did you see the evidence (test results, screenshots) rather than only being told it works? - **Could someone check it?** Did a person other than the builder look at it? - **What did it take from you?** Hours spent, number of times you had to correct it. - **What did it cost?** In money or plan usage, compared with what the same work would have cost another way. - **What surprised you?** Surprises, good and bad, tell you where to be careful next time. Then make one of three decisions: stop, repeat on another small project, or widen to something that matters more. Widening gradually is usually the safer choice. ## Where does Atlas fit? Atlas is a software team of AI engineers built on Claude Code. You talk to one of them, PA, your project assistant, in plain words, and PA shares the work out to specialists who design, build, test and security-check it. Atlas needs your own Claude account (Claude Pro or Max), and its price never includes Claude. Several of its habits suit a pilot. One project is free on your Mac. Work is not called done until it is on the main copy of the code or queued to be, a screen has its test cases and screenshots, and the product's rules pass. Decisions such as production go-lives, spending and deleting data are never made for you. An optional daily budget warns at 50% and 80% and pauses the team at 100%. What Atlas does not do today is choose your pilot or sum it up at the end as a trial. A one-page pilot summary, built into Atlas with nothing to set up, is something that is coming to Atlas. Until then, use the yardstick above and keep your own notes on hours, corrections and plan usage. ## Conclusion A good pilot is small, real and checkable. Pick a low-stakes task, say what "done" means in plain words, keep a person in charge of anything irreversible, cap the spend and the time, and judge the result on evidence. Two weeks of that tells you more than any demo, and it leaves you with a written record to base the bigger decision on. ## Questions people ask ### What is a good first project for an AI coding agent? A small, low-stakes task that is easy to describe and easy to check, such as an internal tool, a small improvement to an existing product, or tests for code that has none. Avoid payments, sign-in or personal data on day one. ### How long should an AI coding agent pilot last? About two weeks is a sensible time box, though that is our suggestion, not a rule from any vendor. What matters is that you set the end date, the budget ceiling and the pass/fail test before you start. ### How do I know the AI's work is correct if I can't read code? Ask for evidence instead of assurances: test results, the command it ran and its output, or screenshots. Anthropic's guidance is that if you cannot verify the work, you should not ship it, and a separate reviewer starting fresh helps. ### What should I do if the agent keeps getting it wrong? Anthropic's guide says that after two failed corrections on the same issue you should clear the conversation and start again with a better, more specific brief. It says a clean session with a better prompt almost always does better than a long one full of corrections. ## About Atlas: A pilot with limits already built in Atlas gives you one project free on your Mac, refuses to call work done until the project's checks pass, and never decides go-lives, spending or deleting data for you. An optional daily budget warns at 50% and 80% and pauses at 100%. A built-in pilot summary is coming to Atlas, with no setup. Until then, scoring the pilot is up to you. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Claude Code overview](https://code.claude.com/docs/en/overview) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude API Version 2026-10-21: What Teams Must Check > Anthropic released Claude API version 2026-10-21 with breaking changes. Here is what changed, who is affected and what to ask your team to check first. Canonical: https://bridge-terminal.com/atlas/blog/claude-api-version-2026-10-21-what-to-check/ Last updated: 2026-10-23 Published 23 October 2026 · Plain English · What's new · 7 min read ## The short version - Anthropic released Claude API version 2026-10-21 on 21 October 2026. It removes some settings and makes some requests fail that used to work. - Only software that calls the Claude API itself is affected. Using Claude Code with a Claude plan is a different route, and the sources do not say it has to change. - The biggest change: the temperature, top_p and top_k settings are removed, and any request that sends one gets a 400 error on every model. - New versions of Anthropic's code libraries (SDKs) use the new API version by default, so a routine library upgrade can bring in these breaking changes. - Ask your team which products call the Claude API, which library version each uses, and whether the upgrade was tested before it reaches customers. If your product calls the Claude API, there is a new version to plan for. On 21 October 2026 Anthropic released API version `2026-10-21`. It removes some settings and makes some requests fail that used to work. If you only use Claude Code to build software, nothing here changes for you. If the software you build talks to Claude, ask your team to check it. This article explains what changed, who is affected and what to ask. It is based on Anthropic's versioning page, its migration guide, the Claude Platform release notes and the Claude Code changelog. ## What is a Claude API version? The Claude API is how software sends requests to Claude and gets answers back. Every request carries a version label, so the API knows which rules to follow. Anthropic's versioning page says that for any given version it keeps the existing inputs and outputs. It may add optional inputs and new output values, and it may change the conditions under which specific errors appear. Breaking changes therefore arrive with a new version label. Earlier SDKs sent the label `2023-06-01` with every request. The new label is `2026-10-21`, and Anthropic recommends using the latest version whenever possible. ## What changed on 21 October 2026? The release notes for that day say the new API version was released, with a migration guide for upgrading. Three changes to the Messages API (the main way to ask Claude for text) are the most likely to affect a product. All three are on the versioning page. - **Three tuning settings are gone.** The `temperature`, `top_p` and `top_k` settings are removed. They controlled how varied or predictable the answers were. A request that sends any of them now gets a 400 error, which is the API's way of saying the request is invalid. This applies on every model. - **A document in the wrong place fails.** A request that puts a `document` block directly in an assistant message returns a 400 error. - **Some citation setups fail.** A `text` block with a non-empty `citations` list in a user message returns a 400 error. The same goes for one inside a `search_result` block. Some field names also changed in the Admin API and the Enterprise Analytics API. For example, API key listings no longer return `workspace_id`; you read `scope.workspace_id` instead. This matters mainly to teams that build their own reports or admin tools on those APIs. ## What changed in Anthropic's code libraries? Anthropic ships code libraries (SDKs) that most teams use instead of calling the API by hand. The migration guide says a library sends the API version that was current when its major version was released. The release notes list the new versions that send `2026-10-21` by default: - Python 2.0.0 - TypeScript 1.0.0 - C# 13.0.0 - Go 2.0.0 - Java 3.0.0 - PHP 1.0.0 - Ruby 2.0.0 - the `ant` command-line tool 2.0.0 The practical point is that upgrading the library is the same step as upgrading the API version. A routine "update dependencies" task can bring in breaking changes. The release notes say these releases also contain breaking changes that do not depend on the API version. The migration guide lists several of them: - The libraries and the `ant` tool now send your API key in an `Authorization: Bearer` header instead of `X-Api-Key`. A header is a labelled line sent along with each request. The guide says the API accepts a key in either one. But anything in between that reads the old header, such as a company gateway or proxy (a server your traffic passes through), a log filter or a test stand-in, needs a change. - A client now holds one credential. Giving it both an API key and a token is an error in the new versions. - The old Text Completions API is removed from the TypeScript, Go, Java and Ruby libraries and from the command-line tool. The Messages API replaces it. - The `ant` tool no longer accepts `--api-key` and `--auth-token` as flags, because a value typed on the command line is visible in shell history and process listings. - The Go library needs Go 1.25 or later. - The libraries and the command-line tool are now licensed under Apache 2.0. Earlier versions stay under the MIT License. The guide says no code changes are needed, but a company that tracks the licenses of its dependencies should update its records. ## Does this affect me if I only use Claude Code? Mostly no. The API version matters to software that calls the Claude API. Claude Code run with a Claude subscription is a different route, and nothing in the sources says your daily use has to change. It does matter in two cases. First, if you are building a product that uses Claude inside it, such as a chat feature, a document reader or a support tool. Second, if you run scripts or automation that call the API with an API key. Claude Code itself gained a helper for this work. Version 2.1.307, released on 21 October 2026, added `/claude-api api-version`, which the changelog describes as a way to move Claude API code to API version `2026-10-21`. The changelog gives only that one line, so treat the result like any other AI-written change and have a person check it. ## What should a team do about it? You do not need to read the migration guide yourself. You do need to ask a few clear questions. These are written for a founder, product owner or manager to put to the team: 1. **Which of our products call the Claude API?** Include internal tools, scripts and automations, not only the main product. 2. **Which library version does each one use, and does anyone plan to upgrade it?** An automatic dependency update can pull in the new major version of the library. 3. **Do we send temperature, top_p or top_k anywhere?** If so, those requests will fail on the new version. Someone has to decide what to do instead. 4. **Does anything sit between our software and the API?** Gateways, proxies, logging tools and test stand-ins may read the old key header. 5. **Are we using habits from older models?** The release notes for 7 October say that code written for Claude Haiku 4.5 can break on Claude Haiku 5.5. Manual extended thinking (`budget_tokens`), the sampling settings and assistant message prefill can each return a 400 error there. The pattern is the same: old habits in requests are being turned into errors. 6. **Where will we try the upgrade first?** The safe order is a test copy, then real checks, then customers. Because the breaking part is an error, not a quiet change, a failed request is visible. That is better than silent wrong answers. But a visible failure in front of customers is still a bad day, so the point of testing first is to find it before they do. ## What does this cost in time and money? The sources I read give no price change for this release, so there is nothing to report on cost. The cost is mostly engineering time: finding the places that send removed settings, updating libraries, and testing. For a small product that is likely a short task. For a product with many integrations, or a gateway in front of the API, it needs real planning. Anthropic says it preserves existing inputs and outputs within a version, so a product that stays on `2023-06-01` should keep behaving as documented. The sources I read do not say how long that version will stay available, so do not assume either way. Check Anthropic's versioning page for current guidance before you decide to wait. ## How Atlas relates to this Atlas is a team of AI engineers built on Claude Code. It runs on your own Claude plan rather than API keys, so this API change does not affect how Atlas itself runs. For the products Atlas builds for you, it does not today have a check that finds out which Claude API version your code uses or warns you when a new one ships. What it does around this: every build is reviewed as it finishes, and everything going out is reviewed together before a production release. Checking for API changes like this one is coming to Atlas, built in, so it needs no setup on your side. Until then, put the questions above to PA, your project assistant in Atlas, or to your own engineers, before you upgrade a library. You can read more on the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Claude API version `2026-10-21` is a real breaking change, but a narrow one. It affects software that calls the Claude API, not people who use Claude Code with a plan. The things to find are removed settings, library upgrades that pull in the new version, and anything that reads the old key header. Ask your team those questions now, test on a copy, and move over when it passes. ## Questions people ask ### What is Claude API version 2026-10-21? It is a new version of the Claude API, released on 21 October 2026. It removes the temperature, top_p and top_k settings and makes some requests return a 400 error that used to work. ### Do I need to change anything if I only use Claude Code? The sources do not say your Claude Code use has to change. The new API version matters to software that calls the Claude API itself, such as a product feature or a script that uses an API key. ### Will upgrading the Claude SDK break my app? It can. The new SDK versions, such as Python 2.0.0 and TypeScript 1.0.0, send API version 2026-10-21 by default and include other breaking changes. Test the upgrade on a copy before it reaches customers. ### Are temperature and top_p gone from the Claude API? On API version 2026-10-21, yes. Anthropic's versioning page says temperature, top_p and top_k are removed and a request that sends any of them returns a 400 error on every model. ### Does Claude Code help with the migration? Claude Code 2.1.307, released on 21 October 2026, added a /claude-api api-version command described as a way to move Claude API code to the new version. Have a person review what it changes. ## About Atlas: Atlas and Claude API upgrades in your product Atlas runs on your own Claude plan, so this API version does not change how Atlas works. For the products it builds, each build is reviewed as it finishes and everything going out is reviewed together before a release. A check for your code's Claude API version is coming to Atlas, built in; until then, put this article's questions to PA. — https://bridge-terminal.com/atlas/ ## Sources - [Claude API versions](https://platform.claude.com/docs/en/api/versioning) - [Migrating to API version 2026-10-21](https://platform.claude.com/docs/en/api/migration-2026-10-21) - [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) - [Claude Code changelog](https://code.claude.com/docs/en/changelog) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Fast Mode for Opus 5.5: Cost and When It Pays](https://bridge-terminal.com/atlas/blog/claude-fast-mode-opus-5-5-cost/) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) --- # Claude Code GitHub Actions: Set Up @claude on Your Repo > Set up Claude Code GitHub Actions: install with /install-github-app, write the @claude workflow, run PR reviews and cron jobs, and cap cost and permissions. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-github-actions-setup-at-claude/ Last updated: 2026-10-22 Published 22 October 2026 · Technical · How-to · 7 min read ## The short version - Claude Code GitHub Actions lets anyone with write access mention @claude in an issue or pull request and get an answer or a pushed commit. - Run /install-github-app from Claude Code for the quick path, or install the app, add a secret and copy one workflow file by hand. - Giving the action a prompt switches it from waiting for @claude to running on any event, such as a pull request opening or a daily cron. - Keep permissions narrow, store credentials only as GitHub secrets, and cap each run with --max-turns and workflow timeouts. - Commits pushed with the default GITHUB_TOKEN do not trigger your CI, so leave that token out of the action's inputs. Claude Code GitHub Actions runs Claude Code inside your repository's workflows, so a teammate can write `@claude fix the TypeError in the dashboard` on an issue and have Claude work on it and push the change. You can set it up with `/install-github-app`, or by hand with one secret and one YAML file. This guide covers both paths, the workflows worth having, and the limits that keep cost and risk down. Everything below comes from Anthropic's documentation for the `claude-code-action`. If you want the general headless pattern outside GitHub, see [Claude Code Headless in CI](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/). ## What does the Claude Code GitHub Action do? It is a GitHub Action (`anthropics/claude-code-action`) that starts Claude Code on a GitHub-hosted runner. It works in two modes, chosen by your workflow configuration: - **Interactive mode**: the workflow has no `prompt` input. Claude waits for the trigger phrase, `@claude` by default, in an issue or pull request comment, a pull request review, or the title or body of a new issue. Progress and results appear as a comment on that issue or PR. - **Automation mode**: the workflow has a `prompt` input. Claude runs without waiting for a mention, on whatever event you chose. By default results go to the workflow run log, not a comment. Use interactive mode for "help me with this" requests and automation mode for things you want on every pull request or every morning. ## How do I install it? You need admin access to the repository either way. ### Quick setup with /install-github-app Install and sign in to the GitHub CLI (`gh auth login`), open `claude` in the repository, and run: ```text /install-github-app ``` Follow the prompts. Claude Code installs the Claude GitHub App, then stores a credential as a repository secret. It reuses an existing API key if it has one; otherwise you choose between a long-lived token from your Claude subscription and a pasted API key. The secret is named `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN`. It then pushes a branch with the workflow files you picked and opens GitHub with a pull request ready to create. Merge that pull request and `@claude` works. Two limits: the command works only with github.com repositories (GitLab and Bitbucket remotes get a notice and exit), and pressing Esc stops setup after the current step finishes. ### Manual setup 1. Install the [Claude GitHub App](https://github.com/apps/claude) on the repository. The action relies on three of its permissions: Contents, Issues and Pull requests, all read and write. 2. Add a repository secret. Use `ANTHROPIC_API_KEY` (a key from the Claude Console) or `CLAUDE_CODE_OAUTH_TOKEN` (generated locally with `claude setup-token`, available on Pro, Max, Team and Enterprise). 3. Copy `examples/claude.yml` from the action's repository into `.github/workflows/`. If you use the OAuth token, change the `anthropic_api_key` line to `claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}`. Then test it by tagging `@claude` in an issue. One thing to know before you approve: GitHub does not let you accept a subset of an app's permissions. The official app requests a wider set than this action uses (including Actions, Checks, Workflows and Discussions). If your organisation wants only Contents, Issues and Pull requests, the docs say to create a custom GitHub App. That covers only this action; Code Review and web auto-fix still need the official app. ## What does a working @claude workflow look like? This is the documented interactive workflow: ```yaml name: Claude Code on: issue_comment: types: [created] pull_request_review_comment: types: [created] jobs: claude: if: contains(github.event.comment.body, '@claude') runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write actions: read steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} ``` The non-boilerplate parts: - `id-token: write` is required for the action's default GitHub App authentication. - `actions: read` lets Claude read CI results on pull requests. - `actions/checkout` gives Claude a local copy of the code. - The `if` line stops runners from starting on comments that do not mention `@claude`. Then write requests like these in a comment: ```text @claude implement this feature based on the issue description @claude how should I implement user authentication for this endpoint? @claude fix the TypeError in the user dashboard component ``` Specific requests need fewer turns, which matters for cost (more below). ### Who can trigger it? Before Claude starts, the action checks the actor. On issue and pull request events the user must have write access; you can list exceptions in `allowed_non_write_users`, which needs your own `github_token`. Bot actors are rejected unless listed in `allowed_bots`, which keeps bots from triggering Claude in a loop. The bot check also applies to scheduled runs, which GitHub attributes to a repository user, usually whoever last changed the `cron` line. ## How do I run a code review on every pull request? Give the action a `prompt`. The docs show a workflow that installs the `code-review` plugin and runs its skill whenever a pull request is opened, updated, reopened or marked ready: ```yaml name: Code Review on: pull_request: types: [opened, synchronize, ready_for_review, reopened] jobs: review: runs-on: ubuntu-latest permissions: contents: read pull-requests: read issues: read id-token: write steps: - uses: actions/checkout@v6 with: fetch-depth: 1 - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} plugin_marketplaces: "https://github.com/anthropics/claude-code.git" plugins: "code-review@claude-code-plugins" prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}" claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"' ``` Two details trip people up. Without `--comment`, Claude posts nothing and the findings sit in the run log. And keep the `claude_args` line even though the skill names the same tool, because the inline-comment server only starts when `--allowedTools` names it. Claude skips draft and closed pull requests, ones it judges trivial or automated, and ones that already carry a comment from Claude. On public repositories, GitHub withholds secrets from fork pull requests, so this runs only for branches in the same repository. For what a review like this does and does not catch, read [AI Code Review with Claude Code](https://bridge-terminal.com/atlas/blog/ai-code-review-claude-code-setup/). If you do not want to maintain a workflow file at all, the docs point to the separate Code Review product. The `prompt` can also be a skill from your own `.claude/skills/` directory. Run `actions/checkout` first so the files are on the runner, then pass `/skill-name`. See [Claude Code Skills](https://bridge-terminal.com/atlas/blog/claude-code-skills-reusable-commands/) for writing one. ## Can it run on a schedule? Yes. With a `prompt` and a cron trigger, the action runs in automation mode. A plain-text prompt gets no shell or GitHub API access until you grant tools with `--allowedTools` in `claude_args` or a `permissions.allow` rule in the `settings` input. This daily report, which runs at 09:00 UTC, uses two GitHub MCP tools, so it needs no checkout: ```yaml name: Daily Report on: schedule: - cron: "0 9 * * *" jobs: report: runs-on: ubuntu-latest permissions: contents: read issues: read id-token: write steps: - uses: anthropics/claude-code-action@v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} prompt: "Generate a summary of yesterday's commits and open issues" claude_args: | --model claude-opus-5-5 --allowedTools "mcp__github__list_commits,mcp__github__list_issues" ``` GitHub runs scheduled workflows only from the default branch, and in public repositories disables the schedule after 60 days without repository activity. ## How do I control cost? Each run uses GitHub Actions minutes and, with an API key, API tokens. With an OAuth token, runs use your Claude subscription instead of API billing. The docs list these levers: - Write specific `@claude` requests, and use issue templates to give context up front. - Keep `CLAUDE.md` concise, since Claude reads it on every run. Put review criteria and code style there; see [CLAUDE.md Best Practices](https://bridge-terminal.com/atlas/blog/claude-md-best-practices-project-instructions/). - Set `--max-turns` in `claude_args`, for example `claude_args: "--max-turns 5 --model claude-sonnet-5"`. - Set workflow-level timeouts and use GitHub's concurrency controls to limit parallel runs. More general token tactics are in [Claude Code Costs](https://bridge-terminal.com/atlas/blog/claude-code-costs-token-usage-limits/). One caution on the OAuth option: the token is tied to the subscription of whoever ran `claude setup-token`. For a secret shared across an organisation, the docs recommend an API key. To avoid a long-lived secret entirely, the action supports workload identity federation through the `anthropic_federation_rule_id` and `anthropic_organization_id` inputs, with `id-token: write`. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry are supported through `use_bedrock`, `use_vertex` and `use_foundry`. ## Why is my CI not running on Claude's commits? The usual cause: GitHub does not trigger workflows on commits made with the default `GITHUB_TOKEN`. If you pass `github_token: ${{ secrets.GITHUB_TOKEN }}` to the action, remove it so it authenticates as the Claude GitHub App, or pass a custom app token. Also check that your CI triggers include the events Claude's pushes produce, such as `push` or `pull_request`. If Claude does not respond at all, check that the app is installed, workflows are enabled, the secret exists, the comment contains `@claude` as a whole word (not `/claude` or `@claude-bot`), and the commenter has write access. ## A safe starting configuration 1. Start with the review workflow only, with read permissions, and watch a week of comments. 2. Add the `@claude` workflow once you trust the review output, and keep branch protection so a human merges. 3. Never commit keys; use GitHub Secrets only. 4. Cap every job with `--max-turns` and a timeout. 5. Upgrade old `@beta` workflows to `@v1`: replace `direct_prompt` with `prompt`, drop `mode`, and move `max_turns` and `model` into `claude_args`. ## Conclusion The setup is small: one app, one secret, one or two workflow files. The limits matter more than the setup: narrow permissions, a turn cap, a concise `CLAUDE.md`, and a human who still merges. If you want review and checks across a whole project without writing workflow files, [Atlas](https://bridge-terminal.com/atlas/) does this on its own board rather than in GitHub workflows. Turning GitHub issues and pull request comments into board tasks is on Atlas's list to build in, so it works without any setup on your side; until then, the `@claude` workflow above is how you act on them from GitHub. ## Questions people ask ### How do I set up Claude Code GitHub Actions? Open claude in your repository and run /install-github-app, then merge the pull request it prepares. Alternatively install the Claude GitHub App, add ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as a repository secret, and copy examples/claude.yml into .github/workflows/. Either way you need admin access to the repository. ### Can I use my Claude Pro or Max subscription instead of an API key? Yes. Run claude setup-token locally, store the result as the CLAUDE_CODE_OAUTH_TOKEN secret and pass it as claude_code_oauth_token. Runs then use your subscription instead of API billing, but the token is tied to the person who generated it, so the docs recommend an API key for secrets shared across an organisation. ### Who can trigger @claude in a repository? By default the commenting user needs write access, and bot actors are rejected unless listed in allowed_bots. You can allow specific users without write access with allowed_non_write_users and your own github_token. ### Why doesn't my CI run on the commits Claude pushes? GitHub does not trigger workflows for commits made with the default GITHUB_TOKEN. Remove that token from the action's inputs so it acts as the Claude GitHub App, or pass a custom app token. ### How do I stop a Claude workflow from costing too much? Set --max-turns in claude_args, add workflow timeouts and concurrency limits, write specific requests and keep CLAUDE.md short. Each run also consumes GitHub Actions minutes. ## About Atlas: Review and checks without writing workflow files A GitHub workflow gives you review and checks only after you build and tune it. Atlas reviews every build as it finishes, returns it releasable or files fix tasks to its builder, and its landing train runs the project's own checks once on up to six merged branches. It does this on its own board, not through GitHub Actions. Turning GitHub issues and pull request comments into board tasks is on Atlas's list to build in, so it works without any setup on your side; until then, the @claude workflow is how you act on them from GitHub. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code GitHub Actions (Claude Code docs)](https://code.claude.com/docs/en/github-actions) - [anthropics/claude-code-action (GitHub)](https://github.com/anthropics/claude-code-action) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Code Review with Claude Code: What It Catches and Misses](https://bridge-terminal.com/atlas/blog/ai-code-review-claude-code-setup/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) --- # Why AI Coding Agents Forget and How to Fix It > AI coding agents start every session blank and can lose early instructions mid-task. Here is why, and the plain-English fixes that make your rules stick. Canonical: https://bridge-terminal.com/atlas/blog/why-ai-coding-agents-forget-project-memory/ Last updated: 2026-10-22 Published 22 October 2026 · Plain English · Explainer · 6 min read ## The short version - A Claude Code session starts with a fresh context window (the agent's working memory), so it does not remember yesterday's conversation unless something was written down. - Inside a long session the working memory fills up. Claude Code clears older tool output first, then summarises the conversation, and detailed early instructions may be lost. - Put lasting rules in a short project instruction file (CLAUDE.md) instead of repeating them in chat. - Written instructions are context, not enforced configuration. Anything that must never happen needs a hook, an automatic check that blocks the action. - If your agent keeps repeating a mistake, ask where the rule is written down before blaming the tool. If you have used an AI coding agent for more than a day, you have probably had this moment: you told it something important on Monday, and on Tuesday it acted as if it had never heard it. The short answer is that these agents do not have memory the way a colleague does. Each session starts blank, and even inside one session the agent can only hold so much at once. This guide explains that limit in plain words, shows how it affects a project, and lists what you can do about it. It is based on the documentation for Claude Code, Anthropic's coding agent. You do not need to write code to apply any of it. ## Why does my AI coding agent forget what I told it? Two different things are going on, and they get mixed up. **First: every new session starts fresh.** The Claude Code documentation says each session begins with a fresh context window, without the conversation history from previous sessions. The "context window" is the agent's working memory for the current conversation. When you close a session and open a new one, yesterday's chat is not in it. **Second: working memory fills up during a long session.** The context window holds your conversation, the files the agent has read, the output of commands it has run, and its standing instructions. As it fills, Claude Code clears older tool output first and then summarises the conversation if needed. The documentation says your requests and key code snippets are preserved, but detailed instructions from early in the conversation may be lost. Think of a capable contractor with a small desk. They can do excellent work, but only with the papers on the desk. When the desk is full, older papers go into a folder and a short note replaces them. The note is useful, but it is not the whole paper. ## What does this look like on a real project? A few everyday examples: - **The naming rule.** You say early on, "Always call customers 'members' on screen, never 'users'." Two hours later, a new screen says "users". The rule was only in the conversation, and the conversation was summarised. - **The repeated question.** Every Monday the agent asks which test environment to use, because nobody wrote the answer anywhere it reads at the start. - **The forgotten decision.** You agreed last week not to touch the billing screens. A fresh session has no idea. None of these mean the tool is broken. They mean the information lived only in a chat. ## How do you make an AI coding agent remember? Write things down in a place the agent reads at the start of every session. Claude Code has two such places. ### A project instruction file you write Claude Code loads a file called CLAUDE.md at the start of each session. It holds instructions you want followed every time: how your product talks to customers, what to avoid, how to run the checks. If your project already has an AGENTS.md file, which other coding agents use, Claude Code can read that in place of a CLAUDE.md. For a non-coder, the practical advice is this: 1. **Say it once, in writing, in plain words.** "Customers are called members on every screen" is better than "keep the wording consistent". 2. **Keep it short and specific.** The documentation says the more specific and concise your instructions, the more consistently Claude follows them. 3. **Keep it current.** An old rule that contradicts a new one confuses the agent just as it would confuse a new hire. 4. **Include what you would tell a new team member on day one**: what the product is for, what is off limits, how you want updates reported. ### Notes the agent writes for itself Claude Code also has "auto memory": notes Claude writes itself based on your corrections and preferences. It decides what to save by judging whether the information would be useful in a future conversation. The first 200 lines or 25KB of the main notes file are loaded at the start of each session. The notes are plain files you can view and edit, and they are worth a glance now and then, because the agent wrote them, not you. ### Put task details in the request Memory files are for lasting rules. Details that belong to one task go in the request itself: the goal, the limits and what "done" looks like. ## Is a written rule a guarantee? No, and this is the part many managers miss. The documentation says Claude treats these files as context, not enforced configuration. A rule in the instruction file is a strong suggestion that is usually followed, not a lock. So sort your rules into two piles: - **Preferences.** Wording, style, how to report progress. Put these in the instruction file. An occasional slip is annoying, not harmful. - **Hard limits.** Never delete customer data, never email real customers, never change payment settings. A sentence is not enough here. The documentation says that to block an action regardless of what Claude decides, you use a hook (it names the PreToolUse hook), which is a small automatic check that runs before an action and can stop it. Ask an engineer to set that up. ## How do you stop a long session from losing the plot? A few habits help, even if you never open a terminal: - **Split big jobs into separate sessions.** One session per feature keeps the working memory cleaner. A fresh session with a good written brief is often safer than a long one that has been summarised several times. - **Re-state the key constraint when a task changes direction.** One sentence is cheap. - **Ask for a status summary before you stop.** "Write down what you did, what is left, and what you decided" gives the next session something to start from. - **Notice the warning signs.** If the agent contradicts earlier choices, repeats questions or undoes agreed work, its working memory is probably crowded. Start fresh with a short written summary. The documentation also describes ways to control what survives. An engineer can run the `/context` command to see what is using space, and can add a "Compact Instructions" section to CLAUDE.md to say what should be kept when the conversation is summarised. Helper agents called subagents work in their own separate working memory and hand back only a summary, which keeps the main conversation lighter. ## What does forgetting cost? It costs rework, and rework costs time and plan usage. If an agent builds three screens with the wrong wording, someone has to find and fix all three. The cheapest moment to prevent that is the moment you write the rule down. ## How Atlas handles this Atlas is a team of AI engineers built on Claude Code, and it works within the same limit. Each engineer is its own Claude Code session with a written role and its own working folder. Work lives on a board in a database, so a task does not depend on anyone's chat. Engineers checkpoint, so after a restart they resume where they stopped. 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. A single page showing what the team currently remembers is on Atlas's list to build in, so it works without any setup on your side; until then, the instruction file and the notes described above are where to check what is written down. You can read more on the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion AI coding agents forget because of how they are built: a blank start each session and a limited working memory within it. You cannot change that, but you can work with it. Write lasting rules down in short, plain words. Keep task details in the request. Split big jobs. For anything that must never happen, ask for a hard block rather than a polite sentence. The next time your agent repeats a mistake, ask one question first: where is that rule written down? ## Questions people ask ### Does Claude Code remember previous conversations? Not by itself. Each session starts with a fresh context window. Knowledge carries across sessions only through the instruction file you write (CLAUDE.md) and the notes Claude saves itself as auto memory. ### Why does my AI agent ignore instructions I gave earlier in the chat? As a long session fills its working memory, Claude Code clears older tool output and then summarises the conversation. Detailed instructions from early on may be lost, so lasting rules belong in the instruction file. ### Is a rule in CLAUDE.md guaranteed to be followed? No. The Claude Code documentation says Claude treats these files as context, not enforced configuration. To block an action regardless, you need a hook, which is an automatic check that runs before the action and can stop it. ### What should I put in a project instruction file if I am not technical? Plain, specific rules you would tell a new team member on day one: the product's purpose, wording to use, off-limits areas and how to report progress. Keep it short and up to date. ### What is a context window? It is the agent's working memory for the current session. It holds your conversation, files it has read, command output, standing instructions and saved notes, and it has a limit. ## About Atlas: Memory that does not live in one chat Atlas keeps work on a board rather than in a conversation, so a task survives a restart: engineers checkpoint and resume where they stopped. Lessons from finished work are passed to future engineers, and lessons that track worse results or higher cost are retired automatically. — https://bridge-terminal.com/atlas/ ## Sources - [How Claude remembers your project (Claude Code docs)](https://code.claude.com/docs/en/memory) - [How Claude Code works (Claude Code docs)](https://code.claude.com/docs/en/how-claude-code-works) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Safety Event: A Log of Every Blocked Action > Claude Code 2.1.307 adds a safety event that logs when a permission rule, auto mode, a safety check, a hook or the sandbox stops an action. What it means. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-safety-event-log-blocked-actions/ Last updated: 2026-10-22 Published 22 October 2026 · Plain English · What's new · 6 min read ## The short version - Claude Code version 2.1.307 adds a record, called a safety event, for each tool call that a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back. - One kind of record covers all five safeguards, so a single log can show which of them acted. - The records are sent through OpenTelemetry, a common standard for passing activity data to a monitoring tool, so someone on your team has to switch it on and point it at a destination. - The value for non-engineers is evidence: you can ask how often the AI was stopped, and by what, instead of trusting that the guardrails work. - The changelog gives only a one-line description, so check the exact contents of the records in your own setup before building reports on them. Can you see how often your AI coding agent was stopped from doing something risky? As of Claude Code version 2.1.307, there is a new way to find out. The changelog lists a `claude_code.safety_event` record, sent for each tool call that a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back. In plain terms, the guardrails around the AI can now leave a trail. This article explains what changed, what it means for a team that is not made up only of engineers, and where Atlas stands on it. ## What is the Claude Code safety event? Claude Code is Anthropic's AI coding agent. Before it does something on a computer, such as running a command or editing a file, several safeguards can step in. The changelog entry for version 2.1.307 names them: - **A permission rule.** A written rule about what the agent may do, may not do, or must ask about first. - **Auto mode.** A mode in which the agent asks for approval less often. - **A safety check.** A check that can stop or question an action. - **A hook.** A small script a team attaches to Claude Code so it runs at set moments in the agent's work. - **The sandbox.** A fenced-off area that limits what a command can reach on the machine. The new safety event is the record these safeguards now produce. The changelog describes it as an OpenTelemetry event "for each tool call a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back". A "tool call" is one action the agent tries, such as running a command. "Prompted" means the person was asked. "Sent back" means the action was returned to the agent rather than carried out. The entry sits under version 2.1.307, which was the newest version at the top of the changelog when I read it on 22 October 2026. The changelog entries I saw carry no dates, so I give none. ## What changed compared with before? Without such a record, you could only see a block if you were watching the screen. If the agent ran overnight, or ten engineers ran agents at once, a refusal could scroll past and nobody would know. Claude Code already sent other kinds of activity records. Its monitoring documentation lists events such as a prompt being submitted, a tool finishing, a permission decision being made, and a plugin being installed or loaded. The safety event is one more kind in that family, aimed at one question: where did a safeguard step in? It is a record, not a new safeguard. Nothing new is blocked because of it. It makes existing stops visible after the fact. ## How do you turn it on? This is a task for whoever looks after your tooling. Claude Code sends this data using OpenTelemetry, a widely used standard for passing activity data to a monitoring tool. According to the monitoring documentation, you need to: 1. Enable telemetry by setting `CLAUDE_CODE_ENABLE_TELEMETRY` to 1. 2. Choose where events go with `OTEL_LOGS_EXPORTER`. The options are `otlp`, `console` and `none`. 3. Set a protocol and an endpoint for the receiving tool. There is no default protocol, so you must set one. The records go nowhere useful on their own. Someone needs to run, or subscribe to, a place that collects them, such as the logging tool your company already uses. One caution. The changelog gives a single sentence about this event. In the monitoring documentation I could read, I did not find a section describing the safety event's individual fields. Before you promise anyone a report, such as "stops per week by project", look at a few real records in your own setup and see what they contain. ## What does it mean for a team? ### For founders and managers Guardrails are easy to claim and hard to prove. A log lets you ask concrete questions: - How often was the agent stopped last month? - Did the stops come mostly from one rule, or from the sandbox? - Did anything change after we loosened a rule? If the agent is never stopped, that is also information. Either the work is calm, or your rules are too loose to matter. Without a record you cannot tell which. ### For testers and analysts You can treat guardrails like any other part of the product and test them. Write a rule, try an action it should stop, and check that a record appears. If none does, the rule may not be doing what you think. This turns "we have safety settings" into something you can verify. ### For engineers and tech leads The log helps you tune. A rule that fires constantly on harmless work wastes everyone's time, and people respond by approving things without reading. A rule that never fires may be set up wrongly. Stops that repeat for the same action show where the agent needs a clearer written instruction. It can also support a review after something goes wrong. If a bad change landed, you can look at what the agent tried, and what was stopped, around that time. ## What are the limits? - **It records, it does not explain.** A log entry says something was stopped. Deciding whether the stop was right is still a human job. - **It needs setup.** Without telemetry switched on and a destination chosen, you get nothing. - **It covers Claude Code only.** It tells you nothing about other tools your team may use. - **Details are thin.** The only public description I found is the changelog line, so field names and content need checking in practice. - **Think about who can read it.** Logs about what an agent did are sensitive. The monitoring documentation says content such as prompts and tool details is off by default and has to be switched on separately. Decide who may see the logs, and what to include, before you collect them. ## Does Atlas handle this? Partly, for now. Atlas is a software team made of AI engineers, built on Claude Code. It has its own guard rules. It refuses to mark work done until the work is on the main branch, or queued to be merged there, and the product's rules pass. It also never decides production go-lives, spending, deleting data, sending anything outside or dropping scope for you. Today it does not gather Claude Code's own safety events into a screen or a report that lists "what was stopped, and by which safeguard". This is on Atlas's list to build in, so it works without any setup on your side. Until then, if you need that, the OpenTelemetry route above is the way. You can read more about the team at the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Version 2.1.307 of Claude Code makes its safeguards observable. Each stop, question or send-back from a permission rule, auto mode, a safety check, a hook or the sandbox can now be written to a log. That will not make an AI agent safer by itself. It does let you check whether your rules do what you meant, and it gives managers and testers something real to look at. If your team already uses Claude Code seriously, ask your engineers to switch it on for one project, read a week of records, and decide what to tighten or loosen from the evidence. ## Questions people ask ### What is the Claude Code safety event? It is a record, named claude_code.safety_event, that Claude Code can send for each tool call that a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted or sent back. The changelog lists it as added in version 2.1.307. ### Does the safety event make Claude Code safer? Not by itself. It does not add a new block. It makes existing stops visible, so you can check that your rules work and tune them. ### How do I turn on Claude Code safety event logging? The event goes out through OpenTelemetry. The monitoring docs say to set CLAUDE_CODE_ENABLE_TELEMETRY to 1, pick an exporter with OTEL_LOGS_EXPORTER, and set a protocol and endpoint for the tool that receives the data. Check the record's fields in your own setup, as the changelog gives only one line. ### Does Atlas show Claude Code safety events? Not yet. Atlas has its own rules, such as refusing to call work done until it is on main and the product's rules pass, but today it does not collect Claude Code's safety events into a screen or report. This is on Atlas's list to build in, so it works without any setup on your side; until then, use the OpenTelemetry route. ## About Atlas: Atlas guards the work; a view of what was stopped is on its list Atlas refuses to mark work done until it is on main or queued to land and the product's rules pass, and it leaves go-lives, spending and deleting data to you. Today it does not collect Claude Code's safety events into a view of what was stopped; this is on Atlas's list to build in, so it works without any setup on your side, and until then the OpenTelemetry route covers it. Atlas is independent of Anthropic and OpenAI. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code changelog (version 2.1.307)](https://code.claude.com/docs/en/changelog) - [Claude Code monitoring usage (OpenTelemetry)](https://code.claude.com/docs/en/monitoring-usage) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) --- # Claude Code Sandbox: Limit Files and Network for Bash > Turn on Claude Code's built-in sandbox: set which files and hosts shell commands can reach, fix what breaks, and know what still runs outside it. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-sandbox-bash-files-network/ Last updated: 2026-10-22 Published 21 October 2026 · Technical · How-to · 7 min read ## The short version - Claude Code's sandbox is an operating-system boundary around shell commands that limits which files they can write and which network hosts they can reach. - It is off by default; run /sandbox or set sandbox.enabled to true, then choose auto-allow or regular permissions. - The sandbox covers shell commands only: file tools, MCP servers and hooks run outside it, and commands you type with ! usually do too. - Grant specific write paths or domains instead of excluding a command; excludedCommands and the unsandboxed retry run without the sandbox's limits. - Set allowUnsandboxedCommands to false to stop blocked commands being retried outside the sandbox, and consider sandbox.failIfUnavailable so a missing dependency does not silently disable it. The Claude Code sandbox is a boundary that the operating system enforces around the shell commands the agent runs. You choose which files those commands can reach and which network domains they can contact. Because the operating system applies the limits while a command runs, Claude Code can run sandboxed commands without asking you to approve each one. This guide shows how to turn it on, tune it and check what it does not cover. It is a different tool from permission rules. Rules decide whether Claude may attempt a tool call; the sandbox decides what a running command can touch. If you have not set rules yet, read [Claude Code Permissions: Allow, Deny Rules and Modes](https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/) first, then come back. ## What does the Claude Code sandbox restrict? According to the Claude Code documentation, the limits apply to Bash, PowerShell and Monitor commands and to the processes they start. The defaults are: | Access | Default | | :- | :- | | Writes | The working directory, a per-user temp directory, and directories you added. Protected paths stay write-denied. | | Reads | Most of the machine, including credential files such as `~/.ssh` and `~/.aws/credentials`. | | Network | No direct route out. Connections go through a proxy on your machine that checks each host against your allowed domains, which start empty. | | Environment variables | Inherited from Claude Code, including any secrets in its environment. | Two details matter. First, reads are wide open by default, so a sandboxed command can read your SSH keys unless you deny that. Second, the environment is inherited, so a secret exported in your shell is visible to commands. Both can be changed with settings, shown below. The sandbox runs on macOS, Linux and WSL2. On native Windows, Claude Code runs commands unsandboxed; to use the sandbox there, run Claude Code inside a WSL2 distribution. It is built on the open source `@anthropic-ai/sandbox-runtime` package. On macOS it uses the built-in Seatbelt framework; on Linux and WSL2 it relies on `bubblewrap` and `socat`. ## How do I turn on the sandbox? The sandbox is off by default. Start a session and run: ```text /sandbox ``` The panel has Mode, Overrides and Config tabs. Config shows the resolved settings. If the panel shows only a Dependencies tab, a required package is missing: install it, restart Claude Code and run `/sandbox` again. Pick a mode on the Mode tab: - **Auto-allow**: sandboxed commands run without a prompt. Some commands still go through the normal permission flow, including those that run outside the sandbox (see below). - **Regular permissions**: the usual prompts stay even when commands are sandboxed. To enable the sandbox across all your projects, set `sandbox.enabled` to `true` in `~/.claude/settings.json`. To try it for one session without writing a file: ```bash claude --settings '{"sandbox": {"enabled": true, "allowUnsandboxedCommands": false}}' ``` That command also closes the escape hatch described later, so a blocked command stays blocked. One warning from the docs: by default, if the sandbox cannot start because a dependency is missing or the platform is unsupported, Claude Code runs commands without sandboxing. To make it exit at startup instead, set `sandbox.failIfUnavailable` to `true`. Teams that treat the sandbox as a security gate should use it. To check the sandbox is working, ask Claude to run `touch ~/sandbox-probe`. Inside the sandbox it should fail with `Operation not permitted` on macOS or `Read-only file system` on Linux and WSL2. Do not type the test yourself at the `!` prompt, because that usually runs outside the sandbox. ## How do I allow writes outside the project? Tools such as `kubectl`, `terraform` or `npm` sometimes write outside the working directory. Grant the specific path rather than removing the tool from the sandbox: ```json { "sandbox": { "enabled": true, "filesystem": { "allowWrite": ["~/.kube", "/tmp/build"] } } } ``` These paths are enforced by the operating system, so child processes respect them too. There is also `filesystem.denyWrite` to block writes to specific paths. ## How do I stop commands reading secrets? Reads default to most of the machine. To block your home directory but keep the project readable, put this in the project's `.claude/settings.json`: ```json { "sandbox": { "enabled": true, "filesystem": { "denyRead": ["~/"], "allowRead": ["."] } } } ``` `allowRead` re-opens reading inside a region that `denyRead` blocks. The location matters: in project settings, `.` resolves to the project root, while the same lines in `~/.claude/settings.json` resolve `.` to `~/.claude`, so your project files would stay blocked. The settings reference also lists a `sandbox.credentials` group that hides or masks credential files and environment variables inside the sandbox, and the docs name the `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` variable for environment secrets. Check the sandbox page for the exact options on your version. ## How do I allow network hosts? Allowed domains start empty. The first time a command needs a new domain, Claude Code prompts for approval. In auto mode, Claude instead names the hosts a command needs on the command itself so the classifier can review them with it. To pre-approve hosts, use `network.allowedDomains`: ```json { "sandbox": { "enabled": true, "network": { "allowedDomains": ["github.com", "*.npmjs.org"] } } } ``` `network.deniedDomains` blocks domains, even inside an allowed wildcard. If you want the opposite trade, `filesystem.disabled` turns off filesystem isolation while keeping network isolation. It is accepted only in user or managed settings, not in project files. ## What happens when a tool does not work in the sandbox? You have three choices, from safest to riskiest. 1. **Widen the boundary a little.** Add one directory with `allowWrite` or one host with `allowedDomains`. The command stays sandboxed. 2. **Exclude the command.** Commands matching `excludedCommands` run outside the sandbox: ```json { "sandbox": { "enabled": true, "excludedCommands": ["docker compose *"] } } ``` Excluded commands still go through the regular permission flow, but they run unsandboxed. Keep patterns narrow: a pattern that covers a script in your working directory, or a tool that acts on a file there, can let Claude write that file and then run it outside the sandbox. 3. **Let Claude retry unsandboxed.** When a command fails in the sandbox, Claude can ask to run it again outside it, using the `dangerouslyDisableSandbox` parameter. How that request is approved depends on your permission mode, and a matching allow rule such as `Bash(curl *)` approves the retry as well. See the docs section on the unsandboxed retry for the per-mode behavior. To remove the retry entirely, set `allowUnsandboxedCommands` to `false`; the Overrides tab presents this as strict sandbox mode. If you would rather be asked on every retry, add an ask rule for `Bash(dangerouslyDisableSandbox:true)`. ## Why does auto-allow still prompt sometimes? Some sandboxed commands go through the normal permission flow anyway, typically because a prefix can change which program runs. An allow rule stops the recurring prompt, but it must match the whole command, including any variable assignment at the front. For example, a rule for `npm test` will not cover `FOO=bar npm test`; the rule needs to include the assignment. Remember that an allow rule also approves an unsandboxed retry of the same command. ## What does the sandbox not cover? The sandbox wraps shell commands only. These run outside it: - Built-in file and web tools (Read, Edit, Write, WebFetch, WebSearch). A `denyRead` entry does not stop the Read tool, and `allowedDomains` does not limit WebFetch. Those follow permission rules. - Command hooks, local MCP servers, plugin monitors, LSP servers, and helpers such as your status line command and `apiKeyHelper`. They run with your full access. - Commands you type yourself at the `!` shell-mode prompt, in most sessions. - Excluded commands and unsandboxed retries, as described above. So pair the sandbox with deny rules for the file tools, and treat hooks and MCP servers as trusted code. If you need one boundary around everything, the docs say to run the Claude Code process itself in a container, virtual machine or the sandbox runtime. For automation, see [Claude Code Headless in CI](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/) for permission choices in non-interactive runs. ## How do I enforce it for a team? Use managed settings. The settings reference marks several keys as managed-only, including `sandbox.network.allowManagedDomainsOnly`, which locks the network allowlist to managed settings, and `sandbox.filesystem.allowManagedReadPathsOnly`, which stops developers re-opening read paths your organization blocked. Combine these with `failIfUnavailable` so a machine without the dependencies does not fall back to running unsandboxed. ## A sensible starting setup 1. Run `/sandbox` and pick auto-allow. 2. Deny reads of `~/` and allow `.` in project settings. 3. Add only the write paths and domains your build actually needs. 4. Set `allowUnsandboxedCommands` to `false` for unattended runs. 5. Add deny rules for the file tools on secrets, since the sandbox will not. 6. Set `failIfUnavailable` to `true` where the sandbox is a requirement. ## Conclusion The sandbox turns "approve every command" into "approve the boundary once". It works best when you keep reads narrow, grant writes and hosts one at a time, and shut the unsandboxed retry for unattended work. It is not a full container: file tools, hooks and MCP servers sit outside it, so treat it as one layer next to permission rules. If you run several agents at once, as [Atlas](https://bridge-terminal.com/atlas/) teams do, the same idea applies per session: each one needs its own boundary. ## Questions people ask ### Is the Claude Code sandbox on by default? No. It is off by default. Run /sandbox in a session or set sandbox.enabled to true in a settings file such as ~/.claude/settings.json. ### Does the Claude Code sandbox protect against everything the agent does? No. It wraps shell commands only. File tools like Read and Edit, MCP servers and hooks run outside it, and commands you type with ! usually do too. File tools follow permission rules. ### How do I let Claude Code write outside the project folder in the sandbox? Add the path to sandbox.filesystem.allowWrite, for example ~/.kube. This keeps the command sandboxed, which is safer than running it outside the sandbox with excludedCommands. ### Does the Claude Code sandbox work on Windows? Not natively: on native Windows, commands run unsandboxed. It runs on macOS, Linux and WSL2, so run Claude Code inside a WSL2 distribution on Windows. ### How do I stop Claude from retrying a blocked command outside the sandbox? Set allowUnsandboxedCommands to false, shown as strict sandbox mode on the /sandbox Overrides tab. Or add an ask rule for Bash(dangerouslyDisableSandbox:true) to be prompted on each retry. ## About Atlas: Boundaries for every engineer's session Atlas runs each AI engineer as its own Claude Code session with its own working folder, so a per-session boundary like the sandbox is the same problem at team scale. A sandbox profile for each engineer role is on Atlas's list to build in, so it works without any setup on your side; until then, check Claude Code's sandbox settings yourself. — https://bridge-terminal.com/atlas/ ## Sources - [Configure the sandboxed Bash tool - Claude Code Docs](https://code.claude.com/docs/en/sandboxing) - [Settings reference - Claude Code Docs](https://code.claude.com/docs/en/settings-reference) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Permissions: Allow, Deny Rules and Modes](https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) --- # Your Role When AI Builds the Software: A Plain Guide > What changes for founders, product owners and managers when AI agents write the code: you decide, define "done" and check evidence. A plain-English guide. Canonical: https://bridge-terminal.com/atlas/blog/your-role-when-ai-builds-your-software/ Last updated: 2026-10-21 Published 21 October 2026 · Plain English · Explainer · 7 min read ## The short version - When AI agents write the code, your job moves from relaying requests to deciding what to build, defining what done looks like and checking the evidence. - Stating a pass-or-fail check up front is the skill that matters most, because an agent stops when its work looks finished, not when it has been proven. - In Anthropic's study of its own engineers, easy-to-check, low-stakes and boring tasks were handed over first; design and taste decisions mostly stayed with people. - You do not need to read code, but you do need to read evidence: test results, screenshots and a plain account of what changed. - Keep decisions that spend money, delete data, contact customers or go live with a named person, and write that rule down. If AI coding agents build your software, your job does not disappear. It moves. You spend less time passing requests along and more time deciding what to build, saying what "done" means, and checking evidence that it is done. An "AI coding agent" here means a program that reads a project, writes and changes code, runs commands and works through a task with little hand-holding. This guide explains the shift in plain terms for founders, product owners, business analysts, testers and managers. It draws on Anthropic's published research on its own engineers and on the Claude Code documentation. ## What does your role become when AI writes the code? Think of the change as going from author to editor. Before, a person wrote the first version and you reviewed the result. Now an agent writes the first version, often quickly, and a person decides whether it is right. Anthropic surveyed 132 of its engineers and researchers in August 2025 about how AI had changed their work. Engineers there increasingly saw themselves as managers of AI agents. One estimated their work had shifted "70%+ to being a code reviewer/reviser rather than a net-new code writer." That is a small group at an AI company, and the figures are self-reported. Anthropic itself says the findings likely do not generalize to other organizations right now. Still, the direction is useful for anyone who leads a project: writing code gets cheaper, and judging it matters more. For you, the same pattern shows up in a few jobs: - **Deciding.** Which problem is worth solving this week, and what is not worth doing at all. - **Defining done.** What must be true for you to accept the work. - **Checking.** Looking at proof, not at promises. - **Owning risk.** Deciding what the agents may never do without a person saying yes. ## What stays with people, and what gets handed over? In the Anthropic study, engineers handed over tasks that were easy to check, low-stakes or boring. Most design and "taste" decisions stayed with people, although the study notes that this line keeps moving as the tools improve. More than half of respondents said they could fully hand over only 0 to 20 percent of their work. A plain translation for a business setting (these examples are ours, not from the study): - **Good to hand over:** a report page that must match an existing one, a rename across the product, a bug with clear steps to reproduce, a form with fixed rules. - **Keep with people:** which customers to serve first, how a screen should feel, what a price change does to trust, whether a shortcut is acceptable. One engineer in the study said the more excited they were about a task, the less likely they were to give it to the AI. That is natural, but check that "boring" is not hiding "risky". A dull task like changing how invoices are rounded can still cost real money if it goes wrong. ## Why "define done" becomes your most valuable skill The Claude Code documentation makes one point early: give the agent a way to check its own work. In its words, the agent "stops when the work looks done," and without a check it can run, "looks done" is the only signal it has. If you offer no check, you become the check, and every mistake waits for you to notice it. You do not have to write the check yourself. You have to say what a good result looks like in terms someone can test. Compare: - Vague: "Make the signup better." - Testable: "A new visitor can sign up with an email and password in under one minute. A wrong password shows a clear message. A duplicate email is refused. Show me a screenshot of each case." The second version gives the agent something to aim at and gives you something to inspect. The documentation's own examples work the same way: instead of "make the dashboard look better," it suggests giving a design, asking for a screenshot of the result and asking the agent to compare the two and fix the differences. The documentation also suggests that for larger features you let the agent interview you first. It asks about edge cases, trade-offs and the hard parts you may not have thought about, then writes a specification, which is a written description of what to build. The most useful specifications, it says, state what is out of scope and end with a step that proves the feature works from start to finish. That is a product owner's craft. ## How do you review work if you cannot read code? You read evidence instead. The documentation advises asking the agent to show evidence rather than claim success: the test output, the command it ran and what it returned, or a screenshot of the result. It adds that reviewing evidence is faster than re-running the check yourself. When an agent reports back, you can ask for: 1. **What changed,** in one plain paragraph, and what deliberately did not change. 2. **Which checks ran** and whether they passed. A tester will recognise this as the test report. 3. **Screenshots or a short walkthrough** of the finished screen or flow. 4. **Anything it is unsure about.** This is our suggestion, not a rule from the sources, but it costs nothing to ask. If you are a tester or analyst, writing the cases that decide whether the work passes is a direct fit for this role. You do not need to run each one by hand to judge whether they cover what matters. One more point from the documentation: a reviewer with a fresh view works better than the agent grading its own work. In its words, a fresh context improves review because the reviewer is not biased toward code it just wrote. You can ask for that explicitly. The same page warns that a reviewer asked to find gaps will usually report some, even when the work is sound, and that chasing every finding leads to over-engineering. So ask the reviewer to flag only problems that affect correctness or your stated requirements. ## What new risks come with this role? The Anthropic authors describe a "paradox of supervision": checking AI work well takes skills that heavy AI use may wear down. Some engineers also reported spending more time debugging and cleaning up AI-written code, and carrying more mental load because they did not write it themselves. Your version of this is quieter. If you approve work you do not understand because the agent sounds sure, you have stopped supervising. A few habits help: - **Do not accept "it works" without evidence.** The documentation's advice is blunt: if you cannot verify it, do not ship it. - **Correct early.** The documentation says that correcting an agent as soon as you see it going off track generally gets better results faster. - **Write down the no-go list.** Spending money, deleting data, contacting customers and going live (releasing to real users) should need a named person's yes. - **Keep a person who can read the code** for reviews of anything involving payments, sign-in or personal data, even if most of your team does not. This is our recommendation, based on the higher cost of mistakes there. ## How does the day-to-day change for each role? These are our views of how the role plays out, not findings from the sources. **Founders and managers.** Fewer status meetings, more decisions. Your questions shift from "when will it be done?" to "what is the check, and did it pass?" **Product owners and analysts.** Your written words become the product. Where a human developer would have asked a question, an agent may guess instead. Be explicit about rules, exceptions and out-of-scope items. **Testers.** You move from clicking through screens toward designing the cases and reading the results. Your judgment about what could go wrong matters more when code appears faster. **Agency owners.** If anyone can produce code quickly, the value you offer is in scoping well, checking well and being the person who answers for the result. ## Where Atlas fits Atlas is a software team made of AI engineers, built on Claude Code. You describe what you want in plain words to PA, your project assistant, and PA shares the work with specialist AI engineers who design, build, test and security-check it, and releases it when you say so. Several parts of that match the habits above. Completion is refused until the work is merged into the main version of the project, and a screen has its test cases and screenshots. Production go-lives, spending, deleting data, sending anything outside and dropping scope are never decided for you. An optional daily budget warns at 50% and 80% and pauses the team at 100%. Atlas runs on your own Claude plan, and several engineers working at once use that plan's limits faster. You can also record a call or walkthrough instead of writing an issue list. Atlas lists the issues raised, and nothing is fixed until a person reviews and approves them. For a wider view of the product, see the [Atlas home page](https://bridge-terminal.com/atlas/). ## The bottom line Your role does not shrink; it sharpens. Decide what matters, say what done looks like in a way that can be tested, read the evidence, and keep the risky decisions with people. ## Questions people ask ### Do I still need developers if AI agents write the code? You still need someone accountable for judging the work, especially for payments, sign-in and personal data. In Anthropic's survey of its own staff, engineers increasingly saw themselves as managers of AI agents, with one estimating their work had become mostly reviewing rather than writing. The group was small and self-selected, so treat it as a direction, not a rule. ### What is the most important skill for a non-technical person working with AI coding agents? Defining done in a way that can be tested. The Claude Code documentation says the agent stops when its work looks done, so a clear pass-or-fail check, such as listed cases and screenshots, is what keeps quality up. ### How can I tell if AI-built work is good if I cannot read code? Ask for evidence: which checks ran and passed, screenshots or a walkthrough, and a plain summary of what changed. The Claude Code documentation notes that reviewing evidence is faster than re-running the check yourself. ### Which decisions should stay with a person? Anything that spends money, deletes data, contacts customers, goes live in production or changes scope is a sensible rule to keep with a named person. Separately, Anthropic's study found that design and taste decisions mostly stayed with people. ### Will AI agents replace product owners and testers? Nothing in Anthropic's study or the Claude Code documentation says so. Anthropic's engineers said it was hard to predict what their own careers would look like. Deciding, specifying and verifying are the parts of the work that product owners and testers already do. ## About Atlas: Keeping the decisions with you, the work with the team This article says your job is to decide, define done and check evidence. In Atlas you talk to PA in plain words, and production go-lives, spending, deleting data, sending anything outside and dropping scope are never decided for you. A screen cannot be called done without its test cases and screenshots. — https://bridge-terminal.com/atlas/ ## Sources - [How AI is transforming work at Anthropic](https://www.anthropic.com/research/how-ai-is-transforming-work-at-anthropic) - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Auto Mode Setup: Teach It Your Environment > Claude Code auto mode blocks what it doesn't know is yours. Since 19 Oct 2026, /auto-mode-setup works on more setups. What it does and what to check. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-auto-mode-setup-environment/ Last updated: 2026-10-22 Published 21 October 2026 · Plain English · What's new · 7 min read ## The short version - Claude Code's auto mode lets a second AI model, called the classifier, review actions instead of asking you each time. It blocks anything irreversible, destructive or aimed outside your environment. - By default the classifier trusts only the folder you are working in and that project's configured git remotes, so pushes to your company's other repositories or storage are blocked until you add them. - Claude Code 2.1.304, released 19 October 2026, made the guided /auto-mode-setup command work on Bedrock, Vertex, Foundry, Claude apps gateway and telemetry-disabled sessions. - The setup command drafts the trusted list for you, but you accept or discard the draft as a whole, so read it before saying yes. - Rules that must never be broken belong in deny rules, which are checked before the classifier and cannot be overridden. If your team uses Claude Code and keeps hitting "denied by auto mode" messages, the fix is now easier to reach. Claude Code version 2.1.304, released on 19 October 2026, made the guided `/auto-mode-setup` command available in more kinds of setup: Amazon Bedrock, Google Vertex, Microsoft Foundry, the Claude apps gateway, and sessions with telemetry turned off. The command teaches auto mode what your company's own systems are, so it stops blocking routine work. This article explains what auto mode is, what changed, and what a founder, product owner or tech lead should decide about it. ## What is auto mode in Claude Code? An AI coding agent does many small things: it edits files, runs commands and talks to the network. In the cautious default, called manual mode, it stops and asks before most of them. That is safe but slow, and people soon click "yes" without reading. In auto mode, a second model, called the classifier, reviews the actions instead of you. According to Anthropic's configuration documentation, it blocks anything irreversible, destructive, or aimed outside your environment. Everything else goes ahead without a prompt. Two details matter for non-engineers: - Auto mode is not the same as "allow everything". Your own deny rules (rules that say "never do this") and any "ask" rules (rules that say "always check with me first") are evaluated before the classifier and still block or prompt. - Per the permission-modes documentation, with Claude Code 2.1.283 or later, auto mode is the built-in starting mode for interactive terminal and VS Code sessions. So many people are already using it without choosing it. ## What changed on 19 October 2026? The release notes for version 2.1.304 (GitHub lists it as released on 19 October) describe `/auto-mode-setup` as "now also available on Bedrock, Vertex, Foundry, Claude apps gateway and telemetry-disabled sessions." The documentation explains the gap: before 2.1.304, the command was missing in sessions where Claude Code does not fetch feature flags, which is what happens with telemetry off, a third-party provider or the gateway. Many companies choose those setups for privacy or procurement reasons. The command itself is not brand new. The documentation lists earlier minimum versions: 2.1.228 or later on Pro, Max and Team plans, and 2.1.283 or later on Enterprise plans or with a Claude Console API key. What is new on this date is the reach. Two other recent changes touch auto mode: - Version 2.1.302 (16 October) added an environment variable, `CLAUDE_CODE_AUTO_MODE_MODEL`, to choose which model the client-side classifier uses. It also made the server-side classifier compact a conversation that is too long for the safety check, instead of denying every checked action. - Version 2.1.304 stopped storing the classifier's context with every request, which makes session files smaller. ## Why does auto mode block things that look normal? Because it does not know your company. According to the documentation, the classifier by default trusts only the folder you are working in and the current repository's configured remotes (the addresses it pushes code to). Anything else counts as outside. So these routine jobs can be blocked until you explain them: - Pushing code to another repository in your company's source-control organisation. - Writing to a shared cloud storage bucket your team owns. - Calling an internal service or dashboard. - Installing packages from your private package registry. The result is a pattern many teams know: the agent works well, then stalls on a perfectly normal step. Someone grants a broad permission to make it stop, and the safety net gets weaker than it should be. The documentation's advice is to tell the classifier about the destination rather than loosen everything. It says repeated denials for the same destination usually mean the classifier is missing context. ## What does /auto-mode-setup actually do? You type the command in an interactive terminal session. Claude Code then drafts a list of "environment entries". These are plain-English sentences saying, for example, which source-control organisation is yours, which storage buckets are trusted and which internal domains are safe. According to the documentation, it always reads: - Your project's instruction file (`CLAUDE.md`), README, config files and git remotes. - Your existing auto mode and permission settings. - The hosts, buckets and command names from commands Claude ran in your recent sessions in that project. It reads these commands, never your messages. It also offers two optional scans: the first word of each command in your shell history, and the remote hosts and names of repositories under your home folder. It asks before scanning. You then see the draft and accept or discard it as a whole. If you accept, it is saved to your personal Claude settings file, and you can edit single entries there afterwards. After saving, it also offers to remove allow rules that auto mode ignores, such as `Bash(*)`, or that approve destructive commands. If a lot of actions get blocked and you have no entries yet, Claude Code shows a dialog offering to run the command for you. The command is not available in cloud sessions; the documentation says to run it in an interactive session in your terminal. ## What should a team decide? The setup command saves time, but it writes down what your company trusts. That is a business decision, not just a technical one. ### 1. Decide who owns the list Someone who understands your systems should read the draft before it is accepted. The list says, in effect, "pushing here is fine, writing there is fine". An engineer or tech lead should confirm each line. A non-technical owner can still ask: "Does this list name anything that holds customer data or production?" ### 2. Name your production targets The documentation describes "protected deployment" and "sensitive remote target" settings. By default, any host or namespace whose name contains `prod` or `production` is treated as sensitive. Naming your real production targets makes the protective rules apply to exactly those instead of that guess. Leaving the go-live step to a person is a sensible habit. ### 3. Use deny rules for things that must never happen Auto mode's own settings are written in plain language that a model reads. For actions that must never run regardless of user intent or classifier configuration, the documentation says to use deny rules in managed settings (the company-wide settings an administrator distributes). They block the action before the classifier is consulted and cannot be overridden. An "ask" rule can add a human checkpoint before pushes and pull requests, even in auto mode. ### 4. Know the limits - The classifier does not read auto mode settings from a project's own settings file, so a repository cannot grant itself trust. Personal settings and company-managed settings are where they live. - Settings from different levels add together. A developer can extend the list but cannot remove entries your company's managed settings provide. The documentation also warns that a developer's own allow entry can override an organisation's softer block rule, so this is not a hard boundary. - A one-off instruction such as "don't push until I review" can be lost when a long conversation is compacted (older messages are shortened to save space). Use a rule for anything durable. ### 5. Check the result After saving, engineers can run `claude auto-mode config` to see the rules in force, and `claude auto-mode critique` to get AI feedback on custom entries that are ambiguous, redundant or likely to cause false blocks. Both commands are in the documentation. ## How does this relate to the risks of AI coding agents? Auto mode trades some oversight for speed. A well-taught classifier reduces needless stops while still blocking things like force pushes and secrets leaving the repository. A badly taught one either nags constantly or, worse, is set up so loosely that it approves things nobody meant to allow. The documentation notes that even in auto mode, pushes to branches named like deploy targets, such as `production`, are judged separately rather than waved through. ## Where does Atlas stand? Atlas is an AI engineering team built on Claude Code (see the [Atlas home page](https://bridge-terminal.com/atlas/)). It keeps a few decisions with people by design: production go-lives, spending, deleting data, sending anything outside and dropping scope are never decided for you. That is a separate layer from Claude Code's own auto mode. Preparing and reviewing auto mode's trusted list is on Atlas's list to build in, so it works without any setup on your side; until then, treat that as something your team still does in Claude Code itself. ## Conclusion Auto mode only works well when it knows what is yours. The 19 October release put the guided setup within reach of more setups, so there is less reason to live with constant blocks or to loosen permissions too far. Run the command, have someone who knows your systems read the draft, keep hard limits in deny rules, and check the effective result afterwards. ## Questions people ask ### What is auto mode in Claude Code? It is a permission mode in which a second model, the classifier, reviews actions instead of asking you each time. According to Anthropic's documentation, it blocks anything irreversible, destructive or aimed outside your environment. Deny and ask rules are still checked first. ### What does /auto-mode-setup do? It reads your project files, settings and commands Claude ran in recent sessions, then drafts a list of trusted repositories, buckets and domains. You accept or discard the draft as a whole, and if you accept it is saved to your personal settings file. ### Why is auto mode blocking my push or file upload? By default the classifier trusts only the working folder and the project's configured git remotes. Other destinations, such as another company repository or a team storage bucket, stay blocked until you add them as trusted. ### Is /auto-mode-setup available on Bedrock or Vertex? Yes, from Claude Code 2.1.304, released on 19 October 2026. That version added it for Bedrock, Vertex, Foundry, Claude apps gateway and telemetry-disabled sessions. It is not available in cloud sessions; run it in an interactive terminal session. ### Should I use auto mode settings or deny rules for hard limits? Use deny rules. The documentation says that for actions that must never run, deny rules in managed settings block the action before the classifier is consulted and cannot be overridden. ## About Atlas: Auto mode and who decides what goes live Auto mode's trusted list says what an AI session may do without asking. Atlas's engineers are Claude Code sessions, and Atlas keeps production go-lives, spending, deleting data and sending anything outside as decisions for a person. Drafting and reviewing auto mode's trusted list is on Atlas's list to build in, so it works without any setup on your side; until then, your team runs /auto-mode-setup in Claude Code and has someone read the draft. — https://bridge-terminal.com/atlas/ ## Sources - [Configure auto mode — Claude Code docs](https://code.claude.com/docs/en/auto-mode-config) - [Choose a permission mode — Claude Code docs](https://code.claude.com/docs/en/permission-modes) - [Claude Code changelog (2.1.302, 2.1.304)](https://code.claude.com/docs/en/changelog) - [Claude Code releases on GitHub](https://github.com/anthropics/claude-code/releases) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Permissions: Allow, Deny Rules and Modes](https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/) - [Claude Code Headless in CI: -p Mode and Safe Permissions](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) --- # Test-First with Claude Code: Failing Tests Before Code > Run test-first development with Claude Code: commit failing tests, block edits to them with a hook, finish on a /goal or Stop hook, then review in a fresh context. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-test-first-workflow-failing-tests/ Last updated: 2026-10-20 Published 20 October 2026 · Technical · How-to · 7 min read ## The short version - Test-first suits a coding agent because a failing test gives it a pass/fail result it can read and iterate against without you. - Write and commit the failing tests in one session, then implement in a fresh one so the code is not shaped around tests the same session just wrote. - A PreToolUse hook that denies edits to test files enforces what a prompt only requests, but it does not see changes made through shell commands, so check git diff on the test folder too. - End the run with /goal or a Stop hook tied to the test command. Put a turn limit in the /goal condition; a Stop hook is overridden after eight consecutive blocks. - Finish with a review in a fresh subagent, told to report only gaps that affect correctness. Can you do test-driven development with Claude Code? Yes, and it suits agents well: a failing test is a check the agent can run, read and iterate against until it passes. The catch is that an agent that writes both the tests and the code can bend one to fit the other. The workflow below keeps them apart. Anthropic's best-practices guide states the underlying idea: Claude stops when the work looks done, and without a check it can run, "looks done" is the only signal available, so you become the verification loop. Test-first is a direct way to build that check before any code exists. ## Why test-first suits a coding agent A test suite turns "looks done" into something measurable: the agent does the work, runs the check, reads the result and iterates until it passes. The docs list a test suite, a build exit code, a linter, or a script that diffs output against a fixture as valid checks. Writing the tests first adds three things: - **A spec you can review.** Test names and assertions are quicker to approve than a large diff. - **A fixed target.** The implementation session cannot redefine "correct" halfway through. - **A natural stopping point.** "All tests in this folder pass" is a condition both you and the agent can verify. The risk is the mirror image. If the same agent controls the tests, one way to reach green is to weaken a test. The rest of this guide is about closing that door. The best-practices guide itself suggests a version of the split: have one Claude write tests, then another write code to pass them. ## Step 1: Write the failing tests in their own session Be specific about the behaviour and the cases. The best-practices guide contrasts "add tests for foo.py" with a scoped version that names the edge case and says to avoid mocks. For a bug, it suggests asking for a failing test that reproduces the issue before the fix. If the change touches several files or you are unsure of the approach, begin in plan mode: start with `claude --permission-mode plan`, or press `Shift+Tab` until the status bar shows plan mode. The guide says planning pays off most when you are unsure of the approach or the change spans multiple files, and that you can skip it if you could describe the diff in one sentence. A prompt for the test session might look like this: ```text Read src/billing/ and the existing tests in test/billing/. Write tests for a new proration function: upgrades mid-cycle, downgrades mid-cycle, a zero-length cycle, and a cancelled subscription. Follow the style of the existing tests. Do not write the implementation. Run the tests and confirm they fail for the right reason (function missing or wrong result), not because of a syntax or import error. ``` The last sentence matters. A test that fails because of a typo proves nothing. Ask the agent to show the failing output and read it yourself. Then commit the tests: ```bash git add test/billing/ git commit -m "Add failing tests for proration" ``` Committing gives you a clean baseline: any later change to those files shows up in `git diff`. ## Step 2: Implement in a fresh session Run `/clear`, or open a new session, before implementing. The guide's advice on context applies: a long session carrying the whole test-writing conversation performs worse than a clean one, and a fresh session means the implementer meets the tests as a given, not as something it authored. Give it a precise brief and a way to stop. The `/goal` command sets a completion condition, and after each turn a model checks whether it holds. The docs recommend a condition with one measurable end state, a stated check and the constraints that matter: ```text /goal npm test -- test/billing exits 0, no file under test/ is modified, and lint is clean. Stop after 20 turns if not met. ``` Details worth knowing from the docs: - The evaluator judges the condition against what Claude has surfaced in the conversation. It does not run commands or read files itself, so the condition must be something Claude's own output can demonstrate, such as a test run. - A turn or time clause ("or stop after 20 turns") bounds how long the goal runs. Claude reports progress against it and the evaluator judges it from the conversation, so it is a stated limit rather than a hard cap. - A goal does not change your permission mode. In manual mode Claude still asks before tool calls your settings do not already allow, such as the test command. Run `/goal` in auto mode, or pre-approve the test command, if you want it unattended. - `/goal` on its own shows status, including turns evaluated and token spend. `/goal clear` removes it. - Evaluation tokens are billed on the small fast model and the docs call them typically negligible next to main-turn spend. If you prefer a deterministic gate over a model-judged one, use a Stop hook instead (Step 4). ## Step 3: Make the tests hard to cheat on A line in the goal condition is a request. A hook is enforcement. Hooks run your commands at fixed points in Claude Code's workflow. The docs state that a `PreToolUse` hook returning a deny blocks the tool even in `bypassPermissions` mode. Exit code 2 also blocks, and what you write to stderr goes back to Claude as the reason. Here is a guard that refuses edits to files under `test/`. The hook input arrives as JSON on stdin. For the file tools the path should be in `tool_input.file_path`, but confirm that with the piped-sample method the docs recommend before you rely on it: ```bash #!/bin/bash # .claude/hooks/protect-tests.sh INPUT=$(cat) FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') case "$FILE" in */test/*) echo "Blocked: tests are fixed for this task. Change the code, not the tests." >&2 exit 2 ;; esac exit 0 ``` ```json { "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-tests.sh" } ] } ] } } ``` Put it in `.claude/settings.json` to share it with the team, make the script executable, and run `/hooks` to confirm it is registered. Test the script by hand: ```bash echo '{"tool_name":"Edit","tool_input":{"file_path":"/repo/test/billing/a.test.ts"}}' | .claude/hooks/protect-tests.sh echo $? # expect 2 ``` There is a gap. Claude can also change files through shell commands, and an `Edit|Write` matcher does not see those. The docs suggest a `Stop` hook that scans the working tree once per turn, or matching `Bash` as well and listing changed files with `git status --porcelain`. For this workflow the simplest check is against the committed baseline: ```bash git diff --quiet HEAD -- test/ || echo "tests changed" ``` Fold that into the Stop hook below, or inspect `git diff -- test/` yourself before merging. Because you committed the tests in Step 1, the answer is unambiguous. ## Step 4: Gate the finish with a Stop hook A `Stop` hook fires whenever Claude finishes responding. Stop hooks use a top-level `decision: "block"` with a `reason`, which Claude takes as its next instruction. This one runs the suite and blocks the stop while it fails: ```bash #!/bin/bash # .claude/hooks/tests-must-pass.sh if ! OUT=$(npm test -- test/billing 2>&1); then jq -n --arg r "Tests still failing. Fix the code, not the tests: $(echo "$OUT" | tail -40)" '{decision: "block", reason: $r}' fi exit 0 ``` Two limits to plan for. First, Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call from Claude in between. If the work legitimately needs more iterations, the docs name `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` for raising the cap. Second, the docs say a hook should parse `stop_hook_active` from its input and exit early when it is `true`, to avoid loops. That is a trade-off: exiting early lets Claude stop with red tests. A model-judged `/goal` with a turn limit may suit long runs, and a Stop hook short ones. Do not use both blindly. They both fire after every turn, so pick the one whose failure mode you prefer. ## Step 5: Review in a fresh context Green tests show the code matches the tests. They do not show the tests were enough. The docs recommend a reviewer running in a fresh subagent context, which sees only the diff and the criteria you give it, not the reasoning that produced the change. Name the work, the plan and what counts as a finding: ```text Use a subagent to review the proration diff against PLAN.md. Check that every requirement is implemented, the listed edge cases have tests, and nothing outside the task's scope changed. Report gaps that affect correctness, not style preferences. ``` The last clause is deliberate. The guide warns that a reviewer prompted to find gaps will usually report some even when the work is sound, and chasing every finding leads to over-engineering. It advises telling the reviewer to flag only gaps that affect correctness or the stated requirements. ## How this looks across a team The same ordering works at team scale, with a person approving each handoff: 1. Tests written and reviewed by a person. 2. Implementation against locked tests. 3. Independent review of the diff. 4. Merge only on a green run of the project's own checks. Atlas, which runs a team of AI engineers on Claude Code, builds part of this order into its board: building waits for an approved architecture, a signed-off design and failing tests, and completion is refused until the work is on main or queued to land and the product's rules pass. You can get most of the benefit on a single machine with the steps above. If you want that ordering without wiring it yourself, see [Atlas](https://bridge-terminal.com/atlas/). ## Common mistakes - **Tests that fail for the wrong reason.** Always read the failing output before committing. - **Mocking everything.** The guide's own example asks for a test that avoids mocks; heavily mocked tests can pass while the real system fails. - **An open-ended goal.** Without a turn or time clause, a stuck run can keep spending your plan. - **Correcting the same issue repeatedly.** After two failed corrections the docs advise `/clear` and a better prompt. - **Trusting the summary.** Ask for the test output as evidence, not the agent's statement that tests pass. ## Conclusion Test-first with an agent is a separation-of-duties problem. Write failing tests in one session, commit them, implement in another, block edits to the tests with a hook, end the run on a measurable condition with a turn limit, and have a fresh reviewer look at the diff. Each step is a few lines of configuration, and together they let you step away from a session without handing over the definition of "correct". ## Questions people ask ### Can Claude Code do test-driven development? Yes. Have it write failing tests first, commit them, then implement in a fresh session until the tests pass. Anthropic's best-practices guide recommends giving Claude a check it can run, and a test suite is the most direct one. ### How do I stop Claude Code from editing the tests to make them pass? Use a PreToolUse hook on Edit and Write that exits with code 2 for test paths, and state in your /goal condition that no test file may change. Claude can also change files through shell commands, which that matcher does not see, so check git diff on the test folder before merging. ### What is the difference between /goal and a Stop hook? Both fire after every turn. /goal is a condition for the current session only, judged by a small fast model from what appears in the conversation. A Stop hook lives in your settings and can run your own script, so the check is deterministic. ### Why does my Stop hook stop blocking after a few tries? Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call from Claude in between. If the work needs more iterations, raise the limit with the CLAUDE_CODE_STOP_HOOK_BLOCK_CAP environment variable. ## About Atlas: Failing tests before building, enforced on the board Atlas runs a team of AI engineers on Claude Code. On its board, building waits for an approved architecture, a signed-off design and failing tests. Completion is also refused until the work is on main or queued to land and the product's rules pass. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Keep Claude working toward a goal (/goal)](https://code.claude.com/docs/en/goal) - [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Plan Mode and Verification Workflow](https://bridge-terminal.com/atlas/blog/claude-code-plan-mode-verify-workflow/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) --- # How AI-Built Software Gets Released: A Plain Guide > What happens between "the AI says it's done" and "customers can use it"? A plain guide to safe releases, with the questions to ask before you say go. Canonical: https://bridge-terminal.com/atlas/blog/how-ai-built-software-gets-released-plain-guide/ Last updated: 2026-10-20 Published 20 October 2026 · Plain English · Explainer · 5 min read ## The short version - A release is a separate step from 'the AI finished the work': it is the moment your customers get the change, so it needs its own checks. - A safe release has a way back, a backup of your data that has been restored as a test, and a check afterwards. Ask to see all three before you approve. - Ask for evidence such as test output and screenshots, not just the agent's claim that it works. - A reviewer that starts with a fresh context is not biased toward code it just wrote, so review should not be left to the session that wrote the code. - The go-live decision should stay with a person, ideally you, because it carries business risk the agent cannot weigh. If you want to know how AI-built software gets released, the short answer is this: the AI finishing a piece of work and your customers receiving it are two different events. Between them sit checks, a plan for going back if something breaks, and a decision by a person. This guide explains each step in plain English, so you know what to ask for before you say "go". ## What is a release, and why is it not the same as "done"? "Done" usually means the agent has built a change and says it works. A release means that change goes to the place where real people use it: your live website, your app, your customer database. The difference matters because mistakes are cheap before a release and expensive after. A bug found on a test copy costs a few minutes. The same bug found by a customer can cost a refund, a support queue, or a lost deal. AI coding agents make this gap easy to forget. They work fast and they report progress confidently. Anthropic's best-practice guide for Claude Code names the risk the "trust-then-verify gap": the agent produces a plausible-looking result that does not handle edge cases (the unusual situations nobody thought to test). Its fix is to always provide verification such as tests, scripts or screenshots, and its rule is: "If you can't verify it, don't ship it." ## The five steps of a careful release Whatever tool builds your software, a careful release has the same shape. You can ask for each step by name. ### 1. Checks that pass on the combined work Software is rarely built in one piece. Several changes are made, then joined together. Each change may work alone and still break something when joined with the others. So the team should run its automatic tests (small programs that check the software behaves as expected) on the combined result, not only on each piece. For you, the question is simple: "Did the tests run on everything that is going out, and did they pass?" ### 2. A fresh pair of eyes The builder should not be the only reviewer. Anthropic's guide says a fresh context improves code review, because the reviewer is not biased toward code it just wrote. It also describes a reviewer that sees only the change and the criteria it was given, not the reasoning that produced the change, so it judges the result on its own terms. The same guide adds a warning: a reviewer asked to find gaps will usually report some, even when the work is sound. It suggests telling the reviewer to flag only problems that affect correctness or the stated requirements, and treating the rest as optional. In everyday terms, it is like asking a colleague to proofread a contract rather than the person who drafted it. ### 3. A way back Before anything goes live, someone should mark the exact state you can return to. Think of saving a copy of a document before a big edit. Be careful with what counts as a "way back". Claude Code has a rewind feature, but its documentation says checkpoints only track changes made through the agent's own file-editing tools. Changes made by running commands are not captured, and checkpoints are meant for quick, session-level recovery. They are not a replacement for version control (the permanent history of every change). A rewind button in the agent's workspace is not the same as a tested route back for your live product. Ask what the way back is, and who has tried it. ### 4. A backup of your data Code can be rolled back from its history. Customer data often cannot. If a release changes how data is stored, a mistake can alter or lose real records. So the sensible order is: back up the data, prove the backup works by restoring it somewhere safe, then rehearse the data changes on that copy. A backup nobody has restored is only a hope. ### 5. Release, then check After the release, the work is not finished. Someone, or something, should confirm the live product works: key pages load, sign-in works, a test order goes through. If a check fails, you use the way back from step 3. ## What should I ask for before I approve a release? You do not need to read code. You need to see evidence. Anthropic's guide recommends having the agent show evidence rather than assert success: "the test output, the command it ran and what it returned, or a screenshot of the result". It notes that reviewing evidence is faster than re-running the verification yourself. Use this short list: - What exactly is going out? A plain list of changes, in words you understand. - Did the automatic tests pass on the combined result? Ask to see the result. - Who or what reviewed it besides the builder? - What is the way back, and how long does it take? - Is my data backed up, and was the backup restored as a test? - What will be checked after release, and by whom? - What is the worst realistic thing that could go wrong? If an answer is "I don't know", that is useful information. Pause and ask. ## Who should press the button? A person. The agent can prepare everything, but the go-live decision carries business risk: timing, customer impact, a campaign running the same day. Those are your calls, not the agent's. A good rule: the team may do the preparing, checking and reporting on its own, but a go-live, spending money, deleting data, or sending something to the outside world should wait for your clear yes. ## How does Atlas handle releases? Atlas, a team of AI engineers built on Claude Code, follows this pattern. Before a production release, everything going out is reviewed together, and a production release waits until the main version of the code passes its checks in full. Releases beyond the Mac follow eight steps: the way back is marked, data is backed up and the backup is proven by restoring it, database changes are rehearsed on that copy, then it is released and checked. Atlas does not decide production go-lives, spending, or deleting data for you; those stay with a person. You can read more on the [Atlas home page](https://bridge-terminal.com/atlas/). ## Common mistakes to avoid - **Treating the agent's "all done" as proof.** Ask for evidence. - **Releasing on a Friday evening with no one watching.** The post-release check needs someone available to act. - **Skipping the backup because the change "only touches the design".** Small changes sometimes touch more than expected. - **Letting the builder review its own work.** Use a separate reviewer. - **Never practising the way back.** The first time you use it should not be during an outage. ## Conclusion A release is a decision, not an event the AI performs for you. The careful version has five parts: combined checks, an independent review, a way back, a proven backup, and a check afterwards. You do not need to understand the code to ask for them. Ask for evidence at each step and keep the final yes in human hands. ## Questions people ask ### What is the difference between 'done' and 'released' in AI-built software? 'Done' means the agent has built a change and reports that it works. 'Released' means real users now receive it. A release needs its own checks, a way back, a backup of your data and a person's decision. ### How do I know an AI coding agent's work is safe to release? Ask for evidence, not claims: test output, screenshots, and a review by something other than the builder. Anthropic's Claude Code guidance says that if you can't verify the work, you shouldn't ship it. ### Why does a release need a backup if the code can be undone? Code has a history you can return to, but customer data often has none. A backup that has been restored as a test shows it will work if a data change goes wrong. ### Can I rely on the agent's undo or rewind feature as my way back? No. Claude Code's checkpoints are meant for quick recovery within a session, do not track changes made through commands, and are not a replacement for version control. Ask for a tested way back for the live product. ### Who should approve the go-live of AI-built software? A person on your side. The agent can prepare and check, but the decision carries business risk such as timing and customer impact, so it should stay with you. ## About Atlas: Releases with a way back, not just a button Atlas follows the careful release pattern described here: everything going out is reviewed together, and beyond the Mac a release marks the way back, backs up data and proves the backup by restoring it, rehearses database changes on that copy, then releases and checks. Production go-lives are never decided for you. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Checkpointing - Claude Code Docs](https://code.claude.com/docs/en/checkpointing) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Review Levels: Quick, Standard and Deep > Claude Code Review now has Quick, Standard and Deep levels and a switch for a whole GitHub organization. What changed on 19 Oct 2026 and what to check. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-review-levels-quick-standard-deep/ Last updated: 2026-10-22 Published 20 October 2026 · Plain English · What's new · 6 min read ## The short version - Since Claude Code 2.1.304 (19 October 2026), Claude's automatic code review on GitHub can be set to Quick, Standard (the default) or Deep, and a deeper review costs more. - An organization owner picks one default level and can give a single repository its own, such as Deep for something critical. Developers cannot change it. - Owners can turn reviews on for every repository in a GitHub organization at once, including ones added later, but this needs a monthly spend limit and Anthropic warns it can raise spend significantly. - A review never approves or blocks a change, it reads code without running it, and it can miss bugs, so a person still decides what ships. - The managed service is for Team and Enterprise plans with GitHub repositories; on any plan you can run a review from your own Claude Code session. Claude Code's Code Review is a service that has Claude read the proposed changes in your GitHub repositories and look for bugs. It now lets you choose how hard it looks. Since Claude Code version 2.1.304, released on 19 October 2026, each review runs at one of three levels: Quick, Standard or Deep. If you are asking "how thorough should my AI code review be, and what does it cost?", this is the new dial. A second change arrived in the same release: an owner can switch reviews on for every repository in a GitHub organization in one step. ## What is Claude Code Review? A pull request is a proposed change to a project. Someone (or an AI agent) asks the team to merge it into the main code. Code Review, from Anthropic, reads each of these changes. According to Anthropic's documentation, several agents read the change together with the code around it, looking for problems such as logic errors, security vulnerabilities and broken edge cases. A separate verification step then checks the candidate findings against the code and filters out false alarms. What remains is ranked by severity and posted as comments on the exact lines, with a summary in the review and a status check (a pass-or-fail style marker GitHub shows on the pull request). That check never reports a failure. Three limits are worth knowing: - A review never approves or blocks a change. The decision to merge stays with your team. - It works by reading the code. It does not build or run it. - Anthropic itself warns that it may miss bugs and security problems, so a review with no findings does not mean the code is free of errors or secure. By default it focuses on correctness: bugs that would break production, not formatting preferences or missing tests. The service is available on Team and Enterprise plans, for repositories hosted on GitHub. Anyone on any plan can still run a review from their own Claude Code session with the `/code-review` command. ## What changed on 19 October 2026? The Claude Code changelog for version 2.1.304 lists two additions under Code Review: 1. **Review levels.** Owners choose Quick, Standard (the default) or Deep for the organization, and can give individual repositories their own level. 2. **Whole-organization coverage.** An option in the admin settings to review every repository in a GitHub organization, including ones added later, without selecting them one by one. ### What do Quick, Standard and Deep mean? The documentation describes each in a line: - **Quick** is a lighter pass. It is the fastest level and the cheapest. - **Standard** balances depth, speed and cost. It is the default. - **Deep** is the most thorough pass. It takes the longest and costs the most. The documentation pages on the service and its setup give no review times or prices for the levels, so do not assume figures. Costs are covered on a separate costs page in the docs. What matters is the trade: more depth means more waiting and more spend. The model itself is not your choice. The docs say Code Review picks the Claude models and the admin settings offer no model choice, so the level is the lever for thoroughness. ### Who sets the level? An owner of the Claude organization, in the admin settings on claude.ai. They choose one default for the organization and can override it for any repository. The documentation's own example is Quick for a routine codebase and Deep for a critical one. A new level applies to reviews that start after the change. Developers have to ask an owner to change the level. What they can do, if they have write access to the repository, is request a review by commenting `@claude review` on a pull request. Those reviews are billed to the organization. ## What does reviewing a whole GitHub organization involve? Before, owners added repositories one at a time. Now they can set the "review runs" option on the organization's row in the repository table. That covers every repository the Claude GitHub App can access, including ones created later. (The GitHub App is the add-on that gives Claude access to your repositories.) Anthropic attaches one warning and three conditions: - The warning: this can raise spend significantly. - The GitHub account connected to Claude must be an owner of that GitHub organization. - The organization must be on github.com. GitHub Enterprise Server instances and personal GitHub accounts are not eligible. - A monthly spend limit must be set, either for your Claude organization or for Code Review. Applying it also changes every repository in that organization to the option you select, including repositories you had set individually. Repositories you had turned off on their own rows stay off. The organization row has no review level of its own, so levels are still set per repository or through the organization default. Separately, each repository chooses when reviews run: once when a pull request is opened, after every push, or only on request. A repository you add starts at "after every push", which runs the most reviews. Combine Deep with "after every push" and the bill climbs quickly. ## What does this mean for a team in practice? The change turns review from a single setting into a budget decision. A few practical ways to use it: - **Match depth to risk.** A marketing site can sit on Quick. Payments, sign-in and anything that handles personal data are candidates for Deep. It is the same logic you would use with human reviewers: more attention where mistakes are expensive. - **Set the spend limit before widening the net.** For whole-organization coverage a monthly limit is required anyway, so pick the number deliberately. - **Use "on request" for busy repositories.** Repositories with many small changes can run reviews only when someone comments `@claude review`, or once per pull request instead of on every push. - **Do not treat a clean review as sign-off.** Anthropic says an empty result does not mean the code is error-free. Keep tests and a human check for anything important. - **Give the reviewer your rules.** The docs say you can steer what gets flagged with `REVIEW.md` and `CLAUDE.md` files in the repository. The review reads `REVIEW.md` from the base or default branch, never from the change being reviewed, so a pull request cannot rewrite its own reviewer's instructions. If you are a founder or manager rather than an engineer, the question to put to your tech lead is simple: "Which of our repositories are on which level, and who decided?" Unless an owner has changed it, the answer is Standard. Some organizations cannot use the service at all. It is not available with Zero Data Retention or the HIPAA configuration, and not yet with customer-managed encryption keys. ## How does Atlas handle code review? Atlas is an AI engineering team built on Claude Code. It reviews on its own terms. Every build is reviewed as it finishes and comes back releasable, or with fix tasks filed to the engineer who built it. Before a production release, everything going out is reviewed together, with security and performance included when switched on. A change touching sign-in, payments or stored secrets gets a security look at once. Choosing a Quick, Standard or Deep review per area of a project is on Atlas's list to build in, so it works without any setup on your side; until then, every build gets the review described above. You can read more on [the Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Claude's Code Review now has a depth setting and an organization-wide switch. Both give owners more control, and both make cost a choice rather than a fixed fact. Decide which code deserves Deep, set a spend limit before covering everything, and keep people and tests as the final check. ## Questions people ask ### What are the Claude Code Review levels? There are three: Quick (a lighter pass, fastest and cheapest), Standard (balanced, the default) and Deep (most thorough, slowest, most expensive). They arrived in Claude Code 2.1.304 on 19 October 2026. ### Who can change the review level? An owner of the Claude organization, in admin settings on claude.ai. They set one default for the organization and can give individual repositories their own level. Developers have to ask an owner. ### Can Claude Code Review review all my GitHub repositories at once? Yes, for an organization on github.com, if the connected GitHub account owns it and a monthly spend limit is set. It covers repositories added later too. Anthropic warns it can raise spend significantly. ### Does Claude Code Review approve or block pull requests? No. It posts comments, a summary and a check, but the merge decision stays with your team. It reads code without running it and may miss bugs, so no findings is not proof of safety. ### Can I get Claude to review code without Team or Enterprise? Yes. The /code-review command runs a review in your own Claude Code session on any plan. The managed service that reviews GitHub pull requests needs a Team or Enterprise plan. ## About Atlas: Review depth per area is on Atlas's list to build in Atlas reviews every build as it finishes and reviews everything together before a production release, with fix tasks filed to the builder by name. Choosing a lighter or deeper review per area of a project is on Atlas's list to build in, so it works without any setup on your side; until then, every build gets that same review. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code Docs: Code Review](https://code.claude.com/docs/en/code-review) - [Claude Code Docs: Set up Code Review](https://code.claude.com/docs/en/code-review-setup) - [Claude Code changelog (2.1.304, 19 October 2026)](https://code.claude.com/docs/en/changelog) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Code Review with Claude Code: What It Catches and Misses](https://bridge-terminal.com/atlas/blog/ai-code-review-claude-code-setup/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) --- # AGENTS.md and CLAUDE.md: One Instruction File for Both > Use one AGENTS.md for Claude Code and Codex: how each tool finds the file, the import and symlink options, size limits, and how to check what loaded. Canonical: https://bridge-terminal.com/atlas/blog/agents-md-claude-md-one-instruction-file/ Last updated: 2026-10-22 Published 19 October 2026 · Technical · How-to · 7 min read ## The short version - Codex reads AGENTS.md; Claude Code (v2.1.277 or later) reads CLAUDE.md first and falls back to AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. - The safest shared setup is one AGENTS.md plus a CLAUDE.md that starts with @AGENTS.md and adds Claude-only notes below. - Claude Code treats CLAUDE.md as context, not enforced configuration, so anything that must always happen belongs in a hook or permission rule. - Keep files short: Claude Code recommends under 200 lines per CLAUDE.md, and Codex stops adding files at 32 KiB by default. - Verify what loaded instead of guessing: /context or /memory in Claude Code, and a 'list the instruction sources' prompt or a log file in Codex. If your team uses both Claude Code and Codex, you can keep one set of project instructions and have both tools read it. Put the shared rules in `AGENTS.md`, which Codex reads natively, and add a short `CLAUDE.md` that imports it. This article shows how each tool finds its files, where they disagree, and how to check what actually loaded. ## Which file does each tool read? Codex reads `AGENTS.md`. Claude Code reads `CLAUDE.md`, and since v2.1.277 it can also read `AGENTS.md` directly. The catch is a precedence rule that surprises people. By default, Claude Code reads your `AGENTS.md` only when there is no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the working directory or any directory above it. If one exists, Claude reads the `CLAUDE.md` files only. Your `~/.claude/CLAUDE.md`, your organisation's managed `CLAUDE.md` and `.claude/rules/` files do not count for that check, and keep loading alongside `AGENTS.md`. | Repository has | Claude Code reads | | :- | :- | | `AGENTS.md` only | `AGENTS.md` | | `AGENTS.md` and `CLAUDE.md` | `CLAUDE.md` only | | `CLAUDE.md` that imports `AGENTS.md` | `CLAUDE.md`, with `AGENTS.md` through the import | A side effect: adding a personal `CLAUDE.local.md` to a project that relies on `AGENTS.md` makes Claude stop reading `AGENTS.md` for you, unless you change the setting described below. Direct reading is also unavailable in some sessions: on versions before v2.1.277, if you disabled the built-in plugin that reads `AGENTS.md`, and in some cases in the first session after an upgrade from v2.1.276 or earlier. Before v2.1.281, some sessions (for example on Amazon Bedrock, or with telemetry disabled) read `CLAUDE.md` files only. In all of these, import `AGENTS.md` from a `CLAUDE.md` instead. ## How does Codex find AGENTS.md? Codex builds its instruction chain from two scopes: - **Global:** in `~/.codex` (or `CODEX_HOME`), it uses `AGENTS.override.md` if present, otherwise `AGENTS.md`. Only the first non-empty file counts. - **Project:** from the project root (usually the Git root) down to the current directory, it checks each directory for `AGENTS.override.md`, then `AGENTS.md`, then any names in `project_doc_fallback_filenames`. At most one file per directory is included. Files are concatenated from root to current directory, so the file closest to your work appears last and overrides earlier guidance. `AGENTS.override.md` replaces `AGENTS.md` in the same folder, which is handy for a temporary change you intend to delete. Codex stops adding files once the combined size reaches `project_doc_max_bytes`, which defaults to 32 KiB. You can raise it, or add fallback names, in `~/.codex/config.toml`: ```toml project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] project_doc_max_bytes = 65536 ``` Claude Code does not read `AGENTS.local.md`, `AGENTS.override.md` or anything under a `.agents/` directory. If you rely on override files for Codex, Claude will not see them. ## Setup 1: AGENTS.md as the single source, CLAUDE.md as an import This is the safest default. It does not depend on the precedence rule above, and it still works in sessions that cannot read `AGENTS.md` directly. Create `AGENTS.md` with the shared rules, then add this `CLAUDE.md` beside it: ```markdown @AGENTS.md ## Claude Code Use plan mode for changes under `src/billing/`. ``` Claude reads the imported file first, then your Claude-specific notes. Relative imports resolve from the file containing them, and imports can nest up to four hops. Claude Code skips an `AGENTS.md` it has already loaded, so keeping the import never makes it read the file twice. ## Setup 2: a symlink If you have nothing Claude-specific to add, a symlink is enough: ```bash ln -s AGENTS.md CLAUDE.md ``` Two constraints from the Claude Code docs. First, Claude's Edit and Write tools refuse to write through a symlink and will redirect to editing `AGENTS.md` instead. Second, on Windows a symlink needs Administrator rights or Developer Mode, and Git checks a committed symlink out as a plain one-line text file unless `core.symlinks` is enabled. If anyone on the team uses Windows, prefer the `@AGENTS.md` import. ## Setup 3: let Claude read both files If you want Claude to always load both, change the **Project instructions** setting. Type `/config` in a session and choose a value: | Value | What Claude reads | | :- | :- | | `claude-md-or-agents-md` | Default: `CLAUDE.md`, or `AGENTS.md` if there is no `CLAUDE.md` or `CLAUDE.local.md` on the path | | `claude-md-and-agents-md` | Both, with each directory's `CLAUDE.md` first | | `claude-md` | `CLAUDE.md` only | | `managed-only` | Only the organisation's managed `CLAUDE.md` and auto memory at launch | You can also set it in `~/.claude/settings.json`, a `--settings` file or managed settings (project and local settings files are ignored for this): ```json { "pluginConfigs": { "cc-plugin-agents-md@builtin": { "options": { "instructionFiles": "claude-md-and-agents-md" } } } } ``` Before v2.1.285 the plugin ID was `agents-md@builtin`; use that ID if older versions also read your settings file. Because this is a personal or managed setting, it does not travel with the repository. Teammates who did not set it get the default. That is why the import in Setup 1 is more reliable for a shared repo. ## What should go in the shared file? Claude Code treats these files as context, not enforced configuration. Its docs say instructions work better when they are specific: - "Use 2-space indentation" rather than "format code nicely" - "Run `npm test` before committing" rather than "Test your changes" - "API handlers live in `src/api/handlers/`" rather than "Keep files organized" Good candidates for the shared file: build, test and lint commands, directory layout that is not obvious, naming conventions, and pitfalls that differ from the tool defaults. Leave out what the agent can read from the code itself, such as dependency lists. Keep the length down. Claude Code warns that files over 200 lines consume more context and may reduce adherence. Codex has the 32 KiB cap noted above. Splitting into `@` imports helps organisation but does not save context, since imported files load at launch. ## Scope rules to parts of the repo Both tools support layering by directory. In Codex, a nested `AGENTS.md` in `services/payments/` is added after the root file when you work there. In Claude Code, a `CLAUDE.md` in a subdirectory loads on demand, when Claude opens a file in that subdirectory. Claude Code also has `.claude/rules/` with path scoping: ```markdown --- paths: - "src/api/**/*.ts" --- # API Development Rules - All API endpoints must include input validation - Use the standard error response format ``` Rules without `paths` load at launch. Rules with `paths` load when Claude reads, writes or edits a matching file. Codex does not read this folder (its documented discovery covers only the `AGENTS.md` names above), so keep anything that both tools need in `AGENTS.md`. ## How do I check what actually loaded? Do not assume. Check in each tool. In Claude Code: - Run `/context` and read the **Memory files** list, or `/memory` to see the paths. Both list an `AGENTS.md` that Claude read directly from v2.1.280; on older versions, ask Claude what its project instructions say. - With no `CLAUDE.md`, an interactive session shows a line like `no CLAUDE.md found; AGENTS.md loaded: `. - Run `claude --version` to confirm v2.1.277 or later for direct `AGENTS.md` reading. - Run `/doctor prompt-audit` (added in v2.1.283) to audit your `CLAUDE.md` files, skills, agents and commands for outdated prompting patterns. It proposes diffs and changes nothing until you ask. In Codex, run from the directory you care about: ```bash codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded." ``` Codex should report the global file, the root `AGENTS.md` and any nested override in that directory. For a plain-text log, start it with `codex -c log_dir=./.codex-log` and read `codex-tui.log` in that folder. There is no cache to clear: restarting Codex in the target directory picks up changes. ## Do not rely on instructions for hard rules The Claude Code docs are explicit that CLAUDE.md content is context, and there is no guarantee of strict compliance. If something must happen every time, such as running a formatter after each edit, use a hook. To block an action regardless of what Claude decides, the docs point to a `PreToolUse` hook; settings such as `permissions.deny` are enforced by the client. ## Migrating an existing setup If you already have a workaround, the Claude Code docs say: - A `CLAUDE.md` containing `@AGENTS.md` can stay. - A `CLAUDE.md` that only says in words to go read `AGENTS.md` is unreliable, since Claude sees `AGENTS.md` only if it decides to open it. Delete it or replace that sentence with an import. - A `CLAUDE.md` symlinked to `AGENTS.md` needs no change. - A `SessionStart` hook that prints `AGENTS.md` should go, because it adds a second copy once Claude reads the file directly. Running `/init` in Claude Code reads Cursor and Copilot rules, and with `CLAUDE_CODE_NEW_INIT=1` set it also reads `AGENTS.md`. `/import` (v2.1.213 or later) appends a one-time copy of another agent's instruction files, such as `AGENTS.md`, to the matching `CLAUDE.md`. ## Conclusion Write your project rules once in `AGENTS.md`, add a `CLAUDE.md` that starts with `@AGENTS.md`, and keep both short and specific. Then verify with `/context` in Claude Code and a "list the instruction sources" prompt in Codex. When a rule must never be broken, move it out of prose and into a hook or permission setting. ## Questions people ask ### Does Claude Code read AGENTS.md? Yes, from v2.1.277. By default it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. Otherwise it reads the CLAUDE.md files only. ### How do I make Claude Code and Codex share one instruction file? Keep the rules in AGENTS.md and create a CLAUDE.md whose first line is @AGENTS.md, with any Claude-only notes below. A symlink from CLAUDE.md to AGENTS.md also works, but it is awkward on Windows and Claude's edit tools will not write through it. ### What is the size limit for AGENTS.md in Codex? Codex's project_doc_max_bytes defaults to 32 KiB across the combined files. Once that is reached it stops adding files, so raise the limit in config.toml or split instructions into nested directories. ### How can I check which instruction files were loaded? In Claude Code run /context or /memory. In Codex, run a prompt asking it to list the instruction sources it loaded, from the directory you are working in, or write a log with -c log_dir. ### Will Claude Code always follow what CLAUDE.md or AGENTS.md says? No. Claude Code's docs say these files are context, not enforced configuration. For rules that must always apply, use hooks or permission rules. ## About Atlas: One set of rules for a team of agents Instruction files only help if every agent actually loads them, and conflicting or oversized files quietly weaken them. Atlas runs each engineer as its own Claude Code session with a written role. Checking a project's AGENTS.md or CLAUDE.md files for conflicts and size is on Atlas's list to build in, so it works without any setup on your side; until then, check what loaded with /context in Claude Code and a "list the instruction sources" prompt in Codex. — https://bridge-terminal.com/atlas/ ## Sources - [How Claude remembers your project (Claude Code docs)](https://code.claude.com/docs/en/memory) - [Custom instructions with AGENTS.md (Codex docs)](https://learn.chatgpt.com/docs/agent-configuration/agents-md) - [Claude Code v2.1.283 release summary](https://www.havoptic.com/r/claude-code-2.1.283) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code vs Codex for Teams: A Workflow Comparison](https://bridge-terminal.com/atlas/blog/claude-code-vs-codex-team-workflows/) - [How to Brief an AI Coding Agent: A Plain-English Guide](https://bridge-terminal.com/atlas/blog/how-to-brief-ai-coding-agent-plain-english/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) --- # What AI Coding Agents Can and Cannot Do: A Plain Guide > What can an AI coding agent do for your product, and where does it still need a person? A plain-English guide with everyday examples for non-coders. Canonical: https://bridge-terminal.com/atlas/blog/what-ai-coding-agents-can-and-cannot-do/ Last updated: 2026-10-19 Published 19 October 2026 · Plain English · Explainer · 7 min read ## The short version - An AI coding agent can read your project, write and change code across many files, run tests and fix what breaks, all from a request in plain words. - It cannot read your mind. It can infer what you mean, but it will fill gaps with its own choices unless you are specific about what you want. - An agent stops when its work looks done, so it needs a check that returns pass or fail, such as tests, a successful build or a screenshot compared with a design. - Performance drops as a long conversation fills up, so short, well-scoped tasks work better than one huge session covering unrelated requests. - Decisions about going live, spending money, deleting data and what to leave out should stay with a person. If you are wondering what an AI coding agent can and cannot do, the short answer is this. It can do much of the hands-on building work: reading a project, writing code, running tests and fixing what breaks. It cannot decide what your business needs, and it cannot reliably prove its own work is right without a check you set up. This guide is for people who do not write code: founders, product owners, analysts, testers and managers. It explains where agents are strong, where they are weak, and what that means for how you work with them. The examples come mostly from Anthropic's public documentation for Claude Code, one widely used agent. ## What is an AI coding agent, exactly? A chatbot answers questions and waits. An agent does things. Anthropic describes Claude Code as "an agentic coding tool that reads your codebase, edits files, runs commands, and integrates with your development tools". The codebase is simply the folder of files that makes up your software. So you can say "add a password reset page" and the agent plans the approach, writes the code across several files and checks that it works. You do not have to dictate each step. That is the real change from older tools that only suggested a line of code at a time. ## What can an AI coding agent do well? These are the jobs where agents earn their keep. ### Build features and fix bugs from plain words Anthropic's documentation says you can describe what you want in plain language. For bugs, you can paste an error message or describe the symptom, and the agent traces the problem through the project, finds the cause and makes a fix. "Customers say login fails after they have been away for an hour" is a usable starting point. ### Do the chores people keep putting off The same documentation lists writing tests for code that has none, fixing style errors across a whole project, resolving merge conflicts (two people having changed the same thing), updating the outside building blocks a product depends on, and writing release notes. These jobs are tedious, rarely urgent and easy to check. That makes them a good fit. ### Answer questions about your own software You can ask how something works, or what happens in an unusual case, much as you would ask another engineer. Anthropic suggests this for getting up to speed on a new codebase. For a new manager or analyst taking over a product, it can be the most useful thing an agent does on day one. ### Work in parallel Anthropic's documentation describes starting several agents that work on different parts of a task at the same time, with a lead agent coordinating the work and merging results. For a founder this means a longer list of work can move at once. ## What can't it do? This is the part that surprises people, so it is worth being blunt. ### It cannot read your mind Anthropic's own advice says it directly: the agent "can infer intent, but it can't read your mind." If you say "make the dashboard look better", it will make some choice, and that choice may not be yours. The documentation's advice is that the more precise your instructions, the fewer corrections you will need. Name the screen, the problem and what "fixed" looks like. ### It cannot tell whether it is right without a check This is the biggest limit. Anthropic's guidance says the agent "stops when the work looks done". Without a check it can run, "looks done" is the only signal it has, and you become the person who must notice every mistake. The guidance names a typical failure: the agent produces "a plausible-looking implementation that doesn't handle edge cases". An edge case is an unusual situation, like a customer with no address, or two people clicking Buy at the same moment. The fix is to give the agent something that returns pass or fail: tests (small programs that check the software behaves correctly), a build that must succeed, or a screenshot compared against a design. Anthropic's blunt rule: "If you can't verify it, don't ship it." For you, this means asking one question about any finished task: what evidence shows it works? Anthropic suggests having the agent show evidence, such as the test output or a screenshot, rather than simply saying it succeeded. ### It does not remember everything, and it gets worse as it fills up An agent works inside a "context window", which holds the whole conversation, every file it has read and every result it has seen. Anthropic notes that performance degrades as this fills, and the agent may start "forgetting" earlier instructions or making more mistakes. In practice, one giant session covering ten unrelated requests is a bad idea. Anthropic recommends resetting between unrelated tasks. If you have corrected the agent more than twice on the same point and it is still wrong, the advice is to start fresh with a better brief rather than keep arguing. ### It does not grade its own homework well Anthropic notes that a fresh session reviews code better, because the agent "won't be biased toward code it just wrote". A reviewer that sees only the finished change and the criteria you give it, not the reasoning behind it, judges the result on its own terms. There is a catch. A reviewer asked to find gaps will usually report some, even when the work is sound, and chasing every finding leads to over-engineering. Anthropic suggests telling the reviewer to flag only gaps that affect correctness or the stated requirements. ### It should not make your business decisions Going live, spending money, deleting data and cutting scope are choices with real consequences. An agent can prepare them and explain the trade-offs. A person should decide. This is our advice rather than a rule from any one vendor, and it follows from the points above: the agent has no way to know your priorities, and some of these actions cannot be undone. ## So what does that mean for my role? Your job moves from describing and chasing to deciding and checking. In practice: - **Founders and product owners** spend less time waiting on build work and more time deciding what is worth building and what "good" looks like. - **Business analysts** become the source of precise requirements: who the user is, what the rules are, what is out of scope. - **Testers** matter more, not less. Someone has to define the checks that the agent works against and to look at the evidence. - **Managers and agency owners** need to watch approvals and who signs off, rather than hours worked. ## A simple way to decide what to hand over Hand over work that is clearly described, easy to check and cheap to undo. Be careful with work that is vague, hard to check or hard to reverse. - Good to hand over: a new report page with clear fields, tests for old code, renaming things consistently, a bug with steps to reproduce. - Hand over with care: anything touching sign-in, payments or customer data. Have a person review it as well. - Keep with a person: pricing choices, launch dates, legal wording, what to leave out. Anthropic also points out that for larger features you can let the agent interview you before it starts. It asks about edge cases, trade-offs and things you may not have considered, then writes a spec, which is a written description of what to build. That is a cheap way to find gaps before they become code. ## How teams add structure around agents A single agent leaves you holding a lot of the checking. Some tools wrap agents in a team structure so the checking is part of the process. Atlas, for example, is a team of AI engineers built on Claude Code. It refuses to call work done until the work is on the main version of the code or queued to join it, a screen has its test cases and screenshots, and the product's rules pass. Every finished build is also reviewed, and decisions such as production go-lives, spending and deleting data are never made for you. You can read more on the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion AI coding agents are strong at doing described, checkable work quickly, and weak at knowing what you meant, knowing whether they are right, and carrying a very long conversation. Treat them as fast builders who need clear briefs, a way to prove their work, and a person making the final calls. Get those three things right and you remove much of the risk while keeping the speed. ## Questions people ask ### What can an AI coding agent do for a non-technical founder? It can build features and fix bugs from plain-language descriptions, write tests, handle chores like updating outside components and writing release notes, and answer questions about how your software works. You still need to decide what to build and check the results. ### Can an AI coding agent build a whole product on its own? It can do a great deal of the building, but it needs clear briefs, a way to check its work and a person making decisions. Without a pass-or-fail check, it stops when work merely looks done. ### Why does an AI coding agent make mistakes on long tasks? Its working memory, called the context window, fills with conversation and files, and performance degrades as it fills. It may forget earlier instructions. Short, well-scoped tasks and fresh sessions give better results. ### How do I know if the code an AI agent wrote is correct? Ask for evidence: test results, a successful build, or screenshots compared with a design. A review by a separate, fresh session also helps, since it is not biased toward code it just wrote. If something cannot be verified, it should not be shipped. ### Which decisions should stay with a person? Going live in production, spending money, deleting data and dropping parts of the plan. An agent can prepare these and explain the trade-offs, but a person should decide. ## About Atlas: Checking built in, so you are not the only check The big limit of any single agent is that nobody checks its work unless you set that up. Atlas builds checks into the team: completion is refused until the work is on main or queued to land, a screen has test cases and screenshots, and the product's rules pass. Every build is reviewed. Production go-lives, spending and deleting data are never decided for you. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code overview](https://code.claude.com/docs/en/overview) - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Hooks Can Now Fail Closed: What It Means > Claude Code 2.1.295 lets a safety check block an action when the check itself breaks. Here is what changed, why it matters and what to ask your team. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-hooks-fail-closed-onfailure-block/ Last updated: 2026-10-22 Published 19 October 2026 · Plain English · What's new · 7 min read ## The short version - Since Claude Code 2.1.295 (8 October 2026), a safety check can be set to block an action if the check itself fails, instead of letting the action through. - Before, on most events, a check that could not start, timed out or gave an unreadable answer did not stop the AI; the action still went ahead. - The new setting is opt-in: if nobody turns it on, a broken check still lets the action go ahead. - A related change in 2.1.299 (14 October 2026) makes allow rules for connected tools reach only the tool server they name. - If your team relies on automatic checks, ask whether they are set to stop the AI when they fail. If you use Claude Code with automatic safety checks, there is a change worth knowing about: a check can now be set to **fail closed**. That means that if the check cannot start, runs out of time or gives an answer Claude Code cannot read, Claude Code stops the action instead of letting it through. The option arrived in Claude Code 2.1.295 on 8 October 2026, and it is off unless someone turns it on. ## What is a Claude Code hook, in plain words? A hook is a small program (or a web service) that Claude Code runs automatically at set moments. For example: just before the AI runs a command on the computer, or just before it accepts your message. The hook looks at what is about to happen and can say "stop". Teams use hooks as guardrails. A hook might refuse any command that deletes files, check that a secret is not being pasted into a file, or run a formatter after every edit. The key point is that a hook is only useful if it actually runs. That is where this change comes in. ## What changed on 8 October 2026? Before this release, a hook that failed did not stop anything on most events. Anthropic's hooks documentation says: "On most events, when a hook fails or times out, Claude Code still carries out the action." Claude Code reported a non-blocking error, and the work carried on. The changelog entry for version 2.1.295, dated 8 October 2026, adds a setting called `onFailure` for command hooks and web (HTTP) hooks. It has two values: - **continue**: the action goes ahead if the hook fails. This is the default, so nothing changes for anyone who does not touch the setting. - **block**: the action is stopped. The documentation says a failure then does what the hook's own "stop" signal (exit code 2) does on that event. For example, a failure on a hook that runs before a tool blocks the tool call, and a failure on a hook that runs when you send a message blocks the message. The one exception is a hook that handles permission requests: there, a failure denies the request. That is the whole feature. It is small, but it closes a quiet gap. ## What counts as a failure? The documentation lists these cases: - The check cannot start, for example because the script it points to does not exist. - A command check ends with an exit code other than 0 or 2. This counts even if it printed an "allow" answer first. - A web check cannot connect, or the response is not a success (2xx) status. - The check reaches its time limit. The default limit for command and web hooks is 600 seconds, lowered to 30 seconds for hooks that run when you send a message, and to 10 seconds for some display events. - The check's JSON output cannot be parsed or does not match the expected format. Plain text from a command check is not counted as a failure. In plain terms: broken, missing, slow or confused. Each of these used to mean "carry on anyway". With the setting on, each means "stop". ## Why does failing closed matter? Think of a door lock that opens whenever its power fails. It works perfectly until the day the power goes out, and that is exactly when you needed it. Safety checks behave the same way. A check that quietly lets everything through when it breaks gives you a false sense of safety. Here are three ordinary ways this can happen on a real project: 1. **A file gets renamed.** Someone tidies the project folder and the check script moves. The hook now cannot start. For weeks the AI runs commands that the hook was meant to review, and nobody notices. 2. **A company server is down.** A web hook asks an internal service whether an action is allowed. The service is offline on a Saturday. The hook cannot connect and the action proceeds. 3. **A slow check times out.** A scan that usually takes ten seconds takes far longer on a large change and hits its time limit. In each case the team believed a rule was enforced when it was not. Fail closed makes the failure visible, because work stops until someone fixes the check. ## What does it cost you? There is a trade-off, and it is worth stating plainly. A check set to block will also block when it breaks for harmless reasons. A flaky internal server can now stop an AI engineer mid-task. For someone waiting on a deadline, that is an irritation. So the choice is about what the check protects: - For rules where a miss is costly, such as blocking deletion of data, or keeping secrets out of the code, failing closed is usually the right choice. - For convenience checks, such as tidying code style, letting work continue is fine. The documentation also notes where the setting has no effect: on hooks that run when the AI tries to stop or finish a task (including subagent stops, task completion and idle teammates), and on command hooks that run in the background. So it is not a blanket switch for every check. If your team uses those kinds of hooks for important rules, ask how they behave on failure. ## What did the permission rules change on 14 October? Another tightening arrived in version 2.1.299 on 14 October 2026. Rules that allow the AI to use a connected tool (an MCP server, which is a plug-in that gives the AI access to something like a database or a ticket system) now reach only the server they name. The changelog says a rule written for a server called `a` no longer allows a server named `a__b` or `a_`. To cover every tool on a server, the rule must use the server's whole name followed by a wildcard. In practice: a rule that was a little too loose before may now allow less than it used to. If the AI suddenly asks permission for a connected tool it used freely last week, this is a likely reason. It is worth a quick look if your team writes its own rules. The same release also fixed a bug where deny and ask rules for a server did not apply when its name contained a double underscore. ## What should a team do about it? You do not need to write code to act on this. Put these questions to whoever sets up your AI tooling: 1. **Do we use hooks at all?** If not, this change does not affect you. 2. **Which of them guard something important?** List them: secrets, deletion, production access, payments. 3. **What happens today if one of them fails?** For most setups the answer is "the AI carries on", because that is the default. 4. **Should those be set to block?** For the important ones, usually yes. 5. **Who gets told when a check breaks?** A blocked action is only useful if someone sees it and fixes the check promptly. Also check that the team is on Claude Code 2.1.295 or later, since the setting does not exist in earlier versions. For a developer, the change is small. Anthropic's own example adds one line, `"onFailure": "block"`, to a hook that screens shell commands, so that a missing script stops the command rather than letting it run. ## How does Atlas relate to this? Atlas is a team of AI engineers built on Claude Code, and it enforces its own rules in a separate way. Completion of a task is refused until the work is on main or queued for the landing train, a screen has its test cases and screenshots, and the product's rules pass. Those checks belong to Atlas itself. Setting up Claude Code hooks and choosing how they behave on failure is on Atlas's list to build in, so it works without any setup on your side; until then, this particular setting is something your own team would configure. You can read more on the Atlas home page at [/atlas/](https://bridge-terminal.com/atlas/). ## Conclusion This release does not add a new kind of check. It changes an old assumption: that a safety check which cannot run is harmless to skip. With `onFailure` set to block, a broken guardrail stops the work instead of disappearing silently. If your team has any automatic check that protects something you care about, find out whether it fails open or closed, and decide on purpose. ## Questions people ask ### What does onFailure block do in Claude Code? It makes Claude Code stop the action if a command or web hook fails, for example because the script is missing, it exits with an unexpected code, times out or returns unreadable output. Without it, the action goes ahead. ### Is the fail-closed setting on by default? No. The default is to continue, so a broken hook still lets the action through unless someone sets onFailure to block. It needs Claude Code 2.1.295 or later. ### Does it work for every kind of hook? No. It applies to command and web hooks. It has no effect on hooks for stopping or finishing a task (Stop, SubagentStop, TaskCompleted, TeammateIdle) or on command hooks that run in the background. ### What changed for MCP permission rules in Claude Code? Since version 2.1.299 on 14 October 2026, an allow rule for an MCP server reaches only the server it names. To cover all of a server's tools, use the server's whole name followed by a wildcard. ## About Atlas: Checks that do not depend on one setting Atlas runs its own gates: a task cannot be marked done until the work is on main or queued to land, a screen has its test cases and screenshots, and the product's rules pass. That is separate from the guardrails you set up in Claude Code itself. Managing those is on Atlas's list to build in, so it works without any setup on your side; until then, your team sets them up in Claude Code. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code hooks reference (onFailure, timeout)](https://code.claude.com/docs/en/hooks) - [Claude Code changelog, October 2026](https://code.claude.com/docs/en/changelog) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Rewind: Undo AI Edits with Checkpoints > How Claude Code checkpoints and /rewind restore code, conversation or both, what they can't undo (Bash, most subagent edits), and how to pair them with git. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-rewind-checkpoints-undo-edits/ Last updated: 2026-10-18 Published 18 October 2026 · Technical · How-to · 7 min read ## The short version - Claude Code captures the state of your code before each prompt that starts a turn. /rewind (or Esc twice on an empty prompt) lets you restore code, conversation, or both. - Rewind only tracks edits made through Claude's file-editing tools. Bash changes such as rm or mv, edits from other sessions and most subagent edits are not undone. - Checkpoints are session-level recovery, not version control: commit to git before risky steps and run git status after a rewind. - The Summarize options in the rewind menu compress part of the conversation without touching your files, like a targeted /compact. Claude Code can undo its own file edits. It automatically captures the state of your code before each prompt you send that starts a turn. You open the rewind menu with `/rewind` (or by pressing `Esc` twice on an empty prompt) to restore code, conversation, or both. It does not track everything, so it works best next to git rather than instead of it. This guide covers how checkpoints work, the six actions in the rewind menu, the cases where rewind does less than you might expect, and a workflow that combines it with git and context management. ## How do Claude Code checkpoints work? Checkpointing is on by default and needs no setup. Per the official checkpointing documentation: - Every prompt you send that starts a turn creates a new checkpoint, capturing the state of your code before Claude acts. - Claude Code keeps file snapshots for the 100 most recent checkpoints in a session. - Checkpoints are saved with the conversation, so you can still run `/rewind` after you resume a session. - Snapshots are deleted in the retention sweep, by default about 30 days after the session last saved one. Rewinding to a checkpoint whose snapshots are gone can fail with `No files were restored`. Set `cleanupPeriodDays` to keep them longer. Only direct edits made through Claude's file-editing tools are tracked. That detail explains most of the limitations below. ## How do I rewind in Claude Code? Two ways to open the menu: ```text /rewind ``` Or press `Esc` twice while the prompt input is empty. If the input contains text, double `Esc` clears it instead. The cleared text is saved to your input history, so press `Up` to get it back. The menu lists the prompts you sent in the session. Pick the point you want to act on, then choose an action: | Action | What it does | | - | - | | Restore code and conversation | Reverts both to that point | | Restore conversation | Rewinds to that message, keeps current code | | Restore code | Reverts file changes, keeps the conversation | | Summarize from here | Compresses the conversation from this point forward | | Summarize up to here | Compresses the conversation before this point, keeps later messages | | Never mind | Back to the list, no changes | The two code-restore options appear only if the selected checkpoint has tracked file changes to revert. After restoring the conversation or choosing Summarize from here, the original prompt from the selected message is put back in the input field so you can edit and re-send it. That makes "same task, better prompt" quick to do. ### Which restore option should I pick? - **Claude went down a wrong path and you want a clean retry:** Restore code and conversation. You get the state before the bad turn, with the prompt ready to edit. - **The code is wrong but the discussion is useful:** Restore code. Claude keeps the conversation, and you can say "that approach broke X, try again". - **The code is fine but the conversation got muddy:** Restore conversation, or use a Summarize option. ## Can I use rewind to free up context? Yes. Summarize keeps you in the same session and compresses context, like a targeted `/compact`. The docs give one use case: summarize a verbose debugging session from the midpoint forward while keeping your initial instructions intact. Summarizing does not change files on disk, and the original messages stay in the session transcript, so Claude can still reference the details. To steer the summary, highlight a Summarize option with the arrow keys and type instructions where the row reads "add context (optional)", then press `Enter`. Selecting an option with its number key summarizes immediately with no instructions. Anthropic's best-practices guide lists the other context tools: - `/clear` resets context between unrelated tasks. - `/compact ` gives more control over compaction, for example `/compact Focus on the API changes`. - Summarize from here / up to here compacts only part of the conversation. - `/btw` asks a side question whose answer never enters conversation history. The same guide gives a rule of thumb: if you have corrected Claude more than twice on the same issue in one session, the context is cluttered with failed approaches. Run `/clear` and start again with a more specific prompt. If you ran `/clear` earlier in the same Claude Code process, the rewind menu shows an extra entry at the top, `/resume (previous session)`. Selecting it resumes the conversation from before the clear. It is available until you exit Claude Code or resume a different session. ## What does rewind not undo? Read this section before you rely on rewind. The documentation lists these gaps. ### Bash commands Files modified by Bash commands are not tracked. If Claude runs `rm file.txt`, `mv old.txt new.txt` or `cp source.txt dest.txt`, rewind cannot reverse it. Only direct file edits made through Claude's file-editing tools are tracked, so anything a shell command changes, such as generated files or installed dependencies, is outside rewind's reach. ### Subagent edits A subagent makes edits with the same file tools, but Claude Code usually does not capture those edits in your session's checkpoints. Rewinding restores only the files Claude had already edited in your conversation. The subagent's edits to other files stay, so use git to revert them. The one documented exception is a skill with `context: fork` that runs in the foreground (set `background: false`). It edits your working tree during your own turn, so rewind restores its edits as usual. A forked skill that runs in the background, which is the default, and a background `/code-review --fix` run are not restored. ### Outside changes Only files edited within the current session are tracked. Manual changes you make outside Claude Code and edits from other concurrent sessions are normally not captured, unless they happen to modify the same files as the current session. If you run several sessions at once, each can rewind only its own work. ### Symlinks and hard links Restore skips any tracked path that is a symlink or hard link and shows a `Restored the code, but skipped N files` warning. The skipped files keep their current contents. Config files that a dotfile manager symlinks into your project and files pnpm hard-links into place are the usual cases. To see which paths were skipped, turn on debug logging with `/debug` before you restore. The log at `~/.claude/debug/.txt` names each one. To undo changes to such a file, ask Claude to reverse the edit or edit it yourself. ### Messages typed mid-turn A message you type while Claude is still working has no checkpoint of its own and can be marked "No code restore". The edits Claude made after reading it count toward the prompt that started the turn. To undo those file changes, select the prompt that started the turn and choose Restore code or Restore code and conversation. That reverts Claude's edits from the whole turn, including those made before your message arrived. ## A workflow that combines rewind and git Treat rewind as the fast inner loop and git as the safety net. 1. **Start from a clean tree.** Commit or stash before a risky task, so anything rewind misses can be reverted with git. 2. **Let Claude try the risky thing.** Anthropic's guide says that instead of planning every move, you can tell Claude to try something risky and rewind if it doesn't work. 3. **Check the result with something that returns pass or fail.** Tests, a build or a linter. The best-practices guide recommends giving Claude a check it can run, and the same check tells you whether a rewind is needed. 4. **If it fails, rewind.** Use Restore code and conversation for a retry, or Restore code to keep the discussion. 5. **After any rewind, run `git status`.** Look for files Bash created or changed, and for anything a subagent touched. Revert those with git. 6. **Commit when green.** The docs are explicit that checkpoints are for quick, session-level recovery and are not a replacement for version control. You can also reduce the risk in step 1 with a permission rule or a hook that blocks destructive Bash commands, since those are exactly what rewind cannot take back. ### Rewind or branch? Summarize keeps you in the same session. If you want to try a different approach while keeping the original session intact, the docs point to `/branch` or `claude --continue --fork-session` instead. Use rewind when you are discarding an attempt, and a branch when you want to keep both. ## Resuming later Checkpoints are saved with the conversation, so closing the terminal does not lose them. `claude --continue` picks up where you left off, and `claude --resume` lets you choose from a list. Naming sessions with `/rename` (for example `oauth-migration`) makes them easier to find. If you resume an old session and expect rewind to work, remember the roughly 30-day default for snapshot retention. ## Conclusion Each prompt that starts a turn is a restore point, and `/rewind` gives you code-only, conversation-only or both. The blind spots are Bash side effects, most subagent edits, other sessions and symlinked or hard-linked files. Keep git as the real record: commit before risky work and check `git status` after a rewind. ## Questions people ask ### How do I undo changes in Claude Code? Run /rewind, or press Esc twice on an empty prompt, pick the prompt you want to go back to, and choose Restore code, Restore conversation, or Restore code and conversation. Only edits made through Claude's file-editing tools are restored. ### Does Claude Code rewind undo Bash commands like rm or mv? No. Checkpointing does not track files changed by Bash commands, so those changes cannot be undone through rewind. Use git to recover them. ### How many checkpoints does Claude Code keep? File snapshots are kept for the 100 most recent checkpoints in a session. Snapshots are also deleted by default about 30 days after the session last saved one, unless you raise cleanupPeriodDays. ### Is rewind a replacement for git? No. The documentation describes checkpoints as quick, session-level recovery and says to keep using version control such as Git for commits, branches and long-term history. ### Can I use /rewind to shrink the context window? Yes. The Summarize from here and Summarize up to here options compress part of the conversation without changing files on disk, like a targeted /compact. ## About Atlas: Undo at the team level, not just the session Rewind covers one Claude Code session on one machine. Atlas runs each engineer as its own Claude Code session in its own working folder, lands finished branches through a train that runs the project's own checks, and never rewrites main's history. Releases beyond the Mac also mark the way back first. — https://bridge-terminal.com/atlas/ ## Sources - [Checkpointing - Claude Code Docs](https://code.claude.com/docs/en/checkpointing) - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) --- # How Much Does an AI Coding Agent Cost? A Plain Guide > What an AI coding agent costs: flat plans versus pay-per-use, Anthropic's published Claude Code averages, why bills climb, and habits that keep spending in check. Canonical: https://bridge-terminal.com/atlas/blog/how-much-does-ai-coding-agent-cost/ Last updated: 2026-10-18 Published 18 October 2026 · Plain English · Explainer · 6 min read ## The short version - An AI coding agent is billed by how much text it reads and writes, not by hours worked, so cost follows the amount of work and how much the agent has to keep in mind. - Anthropic reports that Claude Code costs about $13 per developer per active day, or $150 to $250 a month, across enterprise deployments billed per use. - A flat plan (Claude Pro at $20 a month, Max from $100) trades a surprise bill for usage limits: a rolling five-hour window plus weekly limits. - Costs climb with long sessions, several AI helpers working at once and vague requests; clear briefs and fresh sessions are the cheapest savings. - Start with a small pilot, measure a normal week, then choose a plan or set a spending limit. If you are asking how much an AI coding agent costs, the honest answer is: it depends on how you pay and how much work you give it. Anthropic's documentation for Claude Code, one of the best-known coding agents, says that across enterprise deployments the average cost is around $13 per developer per active day, or $150 to $250 per developer per month. A flat monthly plan can cost less, but it comes with limits on how much you can do. This guide explains what you are paying for, the two main ways to pay, why bills go up, and how to keep them predictable. You do not need to read code to follow it. ## What are you actually paying for? An AI agent does not charge by the hour. It charges by **tokens**. A token is a small chunk of text, roughly a short word or part of one. The agent uses tokens for the text it reads (your request, the project's files, the earlier conversation) and the text it writes (code, explanations, its own reasoning). Think of it like a taxi meter that counts reading and writing instead of kilometres. A short, clear job on one file is a short ride. A vague job on a large project, where the agent has to look around first, is a long one. One point surprises people. Claude Code sends the full conversation with every request, and each time the agent uses a tool it sends another request. So the longer a session runs, the more each new step draws, even for a one-line question. Anthropic's documentation says so directly: a one-line question in a session that has been open all day still draws usage for the whole conversation. ## What are the two ways to pay? ### Pay per use You are billed for the tokens used. Anthropic's Claude Code cost page gives these figures for enterprise deployments: - About $13 per developer per active day on average. - $150 to $250 per developer per month. - Below $30 per active day for 90% of users. Treat these as a rough guide, not a quote. The same page says costs vary widely with the model chosen, the size of the codebase and habits such as running several instances at once or automating work. Its advice is to start with a small pilot group and measure before a wider rollout. ### A flat monthly plan Instead of paying per token, you pay a fixed fee and get a set amount of use. At the time of writing, Anthropic lists Claude Pro at $20 a month ($17 a month with an annual subscription) and Claude Max from $100 a month, offering five or twenty times Pro's usage per five-hour session. Claude Code is included in Pro and Max. The trade-off is limits. Every plan resets on a rolling five-hour window, and paid plans also have weekly limits. Chat and coding draw from the same pool, so a heavy coding day leaves less for chat. Anthropic may also add other caps, such as monthly limits. If you hit a limit, you can wait for the reset or upgrade. On paid plans you can also turn on usage credits, which let you keep working at standard pay-per-use rates. Which is better? A flat plan is easier to budget: the usual worst case is a pause, not a surprise invoice. Pay per use is how organisations that connect agents to their own cloud accounts or the Claude API are billed, and it suits automated or large-scale work where you do not want a ceiling and can watch spending closely. ## Why do AI coding costs climb? Most bill surprises come from a short list of causes, described in Anthropic's cost guidance: - **Long sessions.** Every request carries the full history. Anthropic recommends clearing the conversation between unrelated tasks. - **Coming back after a break.** The system keeps a saved copy of the conversation (a cache) to lower the cost, but it expires. The first message after a long pause reprocesses everything. On a subscription the cache lasts an hour; it drops to five minutes once you are drawing on usage credits. - **Several helpers at once.** Each extra AI helper keeps its own memory of the task and uses its own tokens. Anthropic says agent teams use approximately seven times more tokens than a standard session when the teammates run in plan mode. Parallel work finishes sooner, but it is not free. - **The most powerful model for easy jobs.** Anthropic says its Sonnet model handles most coding tasks well and costs less than Opus, and that Opus is best kept for complex architectural decisions or multi-step reasoning. - **Vague requests.** "Improve this codebase" makes the agent scan broadly. "Add input validation to the login function" lets it go straight to the point. - **Rework.** If the agent builds the wrong thing, you pay twice. Anthropic suggests using plan mode for complex tasks, so the agent proposes an approach for your approval before it builds anything. ## How do you keep costs predictable? You do not need technical skills for most of these. 1. **Write a clear brief.** Say what you want, who it is for, and how you will know it works. It is the cheapest saving there is, because it prevents rework. 2. **Ask for a plan before the work.** A two-minute read of the plan can save an hour of building the wrong thing. 3. **Break big requests into small, separate jobs.** Small jobs keep each session short. 4. **Pilot first.** Run one person or one project for a normal week, look at the usage figures, then decide. 5. **Set a ceiling.** On Team and Enterprise plans, administrators can set spend limits at the organisation, group or individual level. On a personal Pro or Max plan you can set a monthly spend limit on usage credits. 6. **Ask where usage goes.** On Pro, Max, Team and Enterprise plans, Claude Code's usage screen shows recent use broken down by skills, subagents, plugins and connected tools, and flags habits such as long context or cache misses when they account for 10% or more of recent usage. Anthropic says these figures are approximate, but they are still useful for spotting a pattern. ## What does the AI cost compared with a person? This is the question behind the question, and no vendor figure answers it for you. Tokens are only part of the cost. Someone still has to decide what to build, check that it works, and approve releases. A cheap run that produces something nobody can verify is expensive. A more costly run that comes back tested, with evidence, may be the better buy. Judge cost per finished and checked result, not cost per hour of AI time. ## How Atlas fits in [Atlas](https://bridge-terminal.com/atlas/) runs a team of AI engineers on your own Claude Pro or Max plan. It signs in with that plan, so there are no API keys and no per-token API bill; usage counts against the plan, and Atlas's price never includes Claude. Several engineers working at once use the plan's limits faster, and Max gives the most room. You can also set an optional daily budget that warns at 50% and 80% and pauses the team at 100%. ## Conclusion An AI coding agent costs what its reading and writing cost, and that grows with long sessions, many helpers and vague requests. A flat plan keeps the bill predictable. For pay-per-use work, Anthropic's enterprise averages of $150 to $250 per developer per month are a starting point, not a promise. Start small, measure one normal week, write clear briefs, and judge the spend by results that were checked, not by hours of AI activity. ## Questions people ask ### How much does Claude Code cost per month? On a flat plan, Claude Pro is $20 a month ($17 with an annual subscription) and Max starts at $100 a month; Claude Code is included in both. At pay-per-use rates, Anthropic reports about $150 to $250 per developer per month across enterprise deployments. ### Why does an AI coding agent get more expensive in a long session? Claude Code sends the full conversation with every request, so a long session makes each new step draw more usage. Clearing the conversation between unrelated tasks keeps usage lower. ### Is a flat monthly plan cheaper than paying per use? It is often easier to predict, because the usual worst case is waiting for a limit to reset rather than a surprise bill. The trade-off is limits: a rolling five-hour window and weekly caps on paid plans. ### Do several AI agents working in parallel cost more? Yes. Each helper keeps its own memory and uses its own tokens. Anthropic says agent teams use approximately seven times more tokens than a standard session when teammates run in plan mode. ### How can a non-technical manager keep AI coding costs under control? Write clear briefs, ask for a plan before building, split big jobs into small ones, pilot for a week before scaling, and set a spend limit where your plan allows it. ## About Atlas: Atlas runs on your plan, with an optional budget Atlas uses your own Claude Pro or Max plan, with no API keys and no per-token bill, and its price never includes Claude. Several engineers working at once use limits faster, so you can set an optional daily budget that warns at 50% and 80% and pauses the team at 100%. — https://bridge-terminal.com/atlas/ ## Sources - [Manage costs effectively - Claude Code Docs](https://code.claude.com/docs/en/costs) - [Claude pricing](https://claude.com/pricing) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Forked Subagents Now On by Default > Claude Code 2.1.302 (16 Oct 2026) turns on forked subagents in headless runs, the Agent SDK, desktop and VS Code. What a fork is and what to check. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-forked-subagents-default-on/ Last updated: 2026-10-22 Published 18 October 2026 · Plain English · What's new · 6 min read ## The short version - Claude Code 2.1.302 (16 October 2026) turned on forked subagents by default in scripted runs (`claude -p`), the Agent SDK, the desktop app and VS Code. The terminal already had them on. - A fork is a helper that starts with a full copy of the current conversation, so you do not have to re-explain the situation. - Forks share the main session's prompt cache, which the docs say makes them cost less than a fresh helper that needs the same background. - Scripted runs may now spawn forks, so run one job after updating and watch your usage for a few days. - Setting CLAUDE_CODE_FORK_SUBAGENT to 0 turns forks off everywhere; an Agent(fork) deny rule stops Claude spawning them while fork mode stays on. Claude Code 2.1.302, released on 16 October 2026, made "forked subagents" the default in several places where they were not: scripted runs (`claude -p`), the Agent SDK, the desktop app and VS Code. They were already on in the terminal. A fork is a helper that starts with a full copy of your current conversation. If you use Claude Code in scripts or build pipelines, your jobs may behave a little differently after you update. This article explains what a fork is, what changed, and what a team should check. It is based on Anthropic's [Claude Code changelog](https://code.claude.com/docs/en/changelog), its [subagents documentation](https://code.claude.com/docs/en/sub-agents) and its [environment variables reference](https://code.claude.com/docs/en/env-vars). ## What is a forked subagent in Claude Code? A subagent is a helper that Claude starts to do one piece of work on the side. Its own steps stay out of your main conversation, and only the final result comes back. That keeps the main conversation short and focused. Ordinary subagents start fresh. They know only the instructions Claude hands them. That is fine for a narrow job such as "search the code for every place that sends an email." A fork is different. According to the docs, a fork "sees the same system prompt, tools, model, and message history as the main session." Think of it as photocopying the whole conversation and giving the copy to a colleague, instead of writing them a briefing note. The docs say to use a fork when any other helper "would need too much background to be useful", or when you want to try several approaches in parallel from the same starting point. ## What changed on 16 October 2026? Fork mode was already on by default in interactive terminal sessions. The docs say that default needs Claude Code v2.1.232 or later. What was off by default was the non-interactive side: `claude -p` (the mode scripts and build pipelines use) and the Agent SDK, which is Anthropic's toolkit for building your own agents. The 2.1.302 changelog entry says fork subagents are now on by default in `claude -p`, the Agent SDK, the desktop app and VS Code, "as they already are in the terminal". It also says that setting `CLAUDE_CODE_FORK_SUBAGENT=0` turns them off. (That is an environment variable: a named setting you place around a program before it starts.) The same release has two related changes. The desktop app and VS Code now always run the main conversation's subagents in the background, as the terminal does, instead of letting Claude choose. And a subagent's own helper calls in scripted runs, the SDK, the desktop app and VS Code now run in the foreground by default. One caution. When I read it, the subagents documentation page still described fork mode as off by default in `-p` and the SDK. The changelog is the newer statement, so treat it as the current behaviour, and expect the docs to catch up. ## How do forks differ from normal subagents? The docs give a clear comparison: - **Starting knowledge:** a fork gets the full conversation. A normal subagent gets only the prompt it is passed. - **Setup:** a fork uses the same instructions, tools and model as the main session. A normal subagent uses its own definition file. - **Permission questions:** a fork's questions appear in your terminal. A normal subagent running in the background sends its questions to the main session. - **Cache:** a fork shares the main session's prompt cache. A normal subagent has its own. The cache point matters for money. The prompt cache lets the service reuse text it has recently processed instead of starting over, at a lower price. Because a fork starts identical to its parent, its first request can reuse that cache. The docs conclude that a fork "costs less than a fresh subagent for tasks that need the same context." Two more details. A fork cannot start further forks. And when Claude starts a fork, it can ask for the fork's file edits to be written to a separate working copy of the code (a git worktree) instead of your own checkout, which keeps parallel edits from colliding. ## What does this mean for a team? ### Side tasks get easier to hand off With a fork, you can say "draft unit tests for the parser changes so far" without rewriting the background. The helper already knows what you were doing. Several forks can try different approaches from the same starting point, and you compare the results. ### Automated runs may behave differently If your pipeline runs `claude -p`, or you built something on the Agent SDK, Claude may now choose to spawn forks where it previously did not. The docs add that with fork mode on, Claude Code runs the subagents Claude starts in the background and removes Claude's option to ask for the foreground. For a nightly job, that probably does not matter. For a job whose output you compare exactly from run to run, run it once after updating and look. ### Cost: cheaper per helper, but not free A fork carries the whole conversation, so it starts with a lot of text. The cache reuse is what makes that cheaper than briefing a fresh helper on the same background. The sources do not say how much you will save or spend overall. That depends on how often Claude forks and how long the conversation already is. Check your usage after a few days instead of assuming. ### Permissions still apply A fork's permission questions appear in your terminal, as with other work in the session. If you want to keep fork mode on but stop Claude from spawning forks, the docs say to deny the `fork` subagent type with an `Agent(fork)` rule. A deny rule is simply a line in your settings that tells Claude Code never to do a named thing. ## What should we check after updating? 1. **Find out which version you run.** The change is in 2.1.302 (16 October 2026) and later. The desktop app and VS Code are covered too. 2. **Run one automated job and read the result.** Look for anything that changed in order or timing. 3. **Watch usage for a few days.** Compare against your usual pattern, especially if you share a plan across people. 4. **Decide your policy.** Leave forks on, turn them off everywhere with `CLAUDE_CODE_FORK_SUBAGENT=0`, or deny just the fork type. 5. **Tell your team.** In the terminal, background helpers show in a panel below the prompt. The docs say you can open a fork's transcript with Enter and send it follow-up messages, or stop it with `x`. ## How does Atlas handle this? Partly. Atlas is a team of AI engineers built on Claude Code, and each engineer is its own Claude Code session with its own working folder, so engineers never edit the same files under each other. That is Atlas's own way of splitting work in parallel. Claude's forked subagents are a Claude Code feature that happens inside a session, and showing them and their cost per engineer is on Atlas's list to build in, so it works without any setup on your side; until then, watch your usage and choose your fork setting as described above. The team's usage still counts against your Claude plan, and Atlas has an optional daily budget that warns at 50% and 80% and pauses at 100%. To see the whole picture, start at the [Atlas home page](https://bridge-terminal.com/atlas/). ## Conclusion Forked subagents are a sensible idea: a helper that already knows what you are doing, at a lower cost than starting from nothing. The 16 October change extends them from the terminal to scripts, the SDK, the desktop app and VS Code. Update, run one job, watch usage, and choose your setting on purpose. The single switch, `CLAUDE_CODE_FORK_SUBAGENT=0`, is there if you want forks off. ## Questions people ask ### What is a fork in Claude Code? A fork is a subagent, a side helper, that starts with the entire conversation so far, plus the same instructions, tools and model as the main session. Only its final result comes back to your main conversation. ### When did Claude Code turn on forked subagents by default for scripted and SDK use? The Claude Code changelog lists it in version 2.1.302, dated 16 October 2026. It covers claude -p, the Agent SDK, the desktop app and VS Code. They were already on in the terminal. ### How do I turn off forked subagents in Claude Code? Set the environment variable CLAUDE_CODE_FORK_SUBAGENT to 0, which turns fork mode off in every kind of session. To keep fork mode but stop Claude spawning forks, the docs say to add an Agent(fork) deny rule. ### Are forked subagents cheaper than normal subagents? The docs say a fork costs less than a fresh subagent for tasks needing the same context, because its first request reuses the main session's prompt cache. The docs do not give a total saving, so check your own usage. ## About Atlas: Parallel work in Atlas is separate sessions Atlas splits work by giving each AI engineer its own Claude Code session and its own working folder, so engineers never edit the same files. Showing Claude's forked subagents and their cost per engineer is on Atlas's list to build in, so it works without any setup on your side; until then, watch your usage and use Claude Code's fork settings. Usage counts against your Claude plan, and the optional daily budget warns at 50% and 80% and pauses at 100%. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code changelog (version 2.1.302, 16 October 2026)](https://code.claude.com/docs/en/changelog) - [Create custom subagents - Claude Code docs (forked subagents)](https://code.claude.com/docs/en/sub-agents) - [Claude Code environment variables](https://code.claude.com/docs/en/env-vars) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Subagents: When to Split Work and How](https://bridge-terminal.com/atlas/blog/claude-code-subagents-when-to-split-work/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) --- # Claude Code Plan Mode and Verification Workflow > A step-by-step Claude Code workflow: explore in plan mode, write a spec, give the agent a check it can run, then review in a fresh context before you commit. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-plan-mode-verify-workflow/ Last updated: 2026-10-22 Published 17 October 2026 · Technical · How-to · 7 min read ## The short version - Use plan mode when a change touches several files, the approach is uncertain or the code is unfamiliar; skip it when you could describe the diff in one sentence. - Give Claude Code a check it can run, such as tests, a build or a linter, so it iterates until the check passes instead of stopping when the work merely looks done. - For larger features, have Claude interview you, write a spec to a file, and implement it in a fresh session with clean context. - Make the check stricter as the run gets less supervised: a prompt, then a /goal condition, then a Stop hook that blocks the turn until the check passes, or a verification subagent for a second opinion. - Have a second session or subagent review the diff in fresh context, and tell it to flag only gaps that affect correctness or the stated requirements. A reliable way to get good results from Claude Code is a loop of four steps: explore and plan without editing, implement against a written plan, give the agent a check it can run, and review the result in a fresh context. This article walks through that plan mode workflow with the keys, flags and prompts to use, based on Anthropic's best-practices guidance for Claude Code. Most of the advice rests on one constraint: Claude's context window fills up fast, and performance degrades as it fills. Every message, every file Claude reads and every command output sits in that window. Good workflows keep it clean and give the agent a way to know when it is finished. ## Why does Claude Code need a workflow at all? Claude stops when the work looks done. The docs put it plainly: without a check it can run, "looks done" is the only signal available, and you become the verification loop. Every mistake waits for you to notice it. Two habits fix most of this: - Separate research and planning from implementation, so the agent does not solve the wrong problem. - Attach a pass/fail check to every task, so the agent can find its own mistakes. The workflow below assumes your build and test commands are written down in your project's CLAUDE.md file, which Claude reads at the start of every conversation. ## How do I use plan mode in Claude Code? In plan mode Claude reads files and answers questions without making changes. Claude Code blocks edits until you approve a plan. There are two ways in: ```bash # start a session in plan mode claude --permission-mode plan ``` Or, inside a running session, press `Shift+Tab` until the status bar shows `⏸ plan mode on`. The recommended flow has four phases. ### 1. Explore Ask for understanding, not changes: ```text read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets. ``` If the research is large, tell Claude to use subagents. A subagent runs in its own context window and reports back a summary, which keeps your main conversation free for the real work. ### 2. Plan ```text I want to add Google OAuth. What files need to change? What's the session flow? Create a plan. ``` Press `Ctrl+G` to open the plan in your text editor and edit it directly before Claude proceeds. This is the cheapest place to catch a wrong approach: a deleted line in a plan costs nothing, while a wrong assumption spread across ten files costs a revert. ### 3. Implement Approve the plan, or press `Shift+Tab` to leave plan mode, and tell Claude to verify against it: ```text implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures. ``` ### 4. Commit ```text commit with a descriptive message and open a PR ``` ### When should I skip plan mode? Plan mode adds overhead. For tasks where the scope is clear and the fix is small, such as a typo, a log line or a rename, ask Claude to do it directly. Planning pays off when you are unsure of the approach, when the change modifies several files, or when you do not know the code well. The docs give a rule of thumb: if you could describe the diff in one sentence, skip the plan. ## How do I give Claude Code a way to verify its work? The docs call this the difference between a session you watch and one you walk away from. Give the agent something that produces a pass or fail: a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a browser screenshot compared with a design. The difference in prompts is concrete: | Vague | With a check | | - | - | | "implement a function that validates email addresses" | "write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing" | | "the build is failing" | "the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don't suppress the error" | | "fix the login bug" | "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it" | Note the last row: writing a failing test first gives the agent a target and leaves you with a regression test afterwards. Ask for evidence rather than assertions: the test output, the command that ran and what it returned, or a screenshot. Reviewing evidence is faster than re-running the verification yourself, and it works for sessions you were not watching. After Claude's check passes, you can also run `/verify` yourself to confirm the change against the running app. ### How strictly should the check gate the work? The docs describe four levels. Pick one by how much supervision the run will have. 1. **In one prompt.** Ask Claude to run the check and iterate in the same message. This works on any task today. 2. **Across a session.** Set the check as a `/goal` condition. A separate evaluator re-checks it after every turn and Claude keeps working until the goal resolves. If Claude stalls, Claude Code eventually stops the run with the goal still set. 3. **As a deterministic gate.** A Stop hook runs your check as a script and blocks the turn from ending until it passes. The hooks reference describes the cap on consecutive blocks. 4. **By a second opinion.** A verification subagent, or a dynamic workflow that checks its own findings, has a fresh model try to refute the result, so the agent doing the work is not the one grading it. Each step trades setup effort for less of your attention. The docs say the `/goal` and Stop hook versions are what let an unattended run finish correctly without you. ## How do I write a spec for a bigger feature? For larger features, let Claude interview you. Start with a minimal prompt and ask it to use the `AskUserQuestion` tool, replacing the bracketed text with your feature: ```text I want to build [brief description]. Interview me in detail using the AskUserQuestion tool. Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered. Keep interviewing until we've covered everything, then write a complete spec to SPEC.md. ``` Then start a fresh session to execute the spec. The new session has clean context focused on implementation, and you have a written document to point at. The docs say the most useful specs are self-contained: they name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step that proves the feature works. Time spent making the spec precise pays off more than time spent watching the implementation. ## How do I review the result? Use a different context from the one that wrote the code. A reviewer in a fresh subagent sees only the diff and the criteria you give it, not the reasoning that produced the change, so it judges the result on its own terms. The bundled `/code-review` skill reviews the current diff for bugs in a fresh subagent and returns the findings to your session. To check against your plan instead, write the prompt yourself. Name the work, the plan to check it against and what counts as a finding: ```text Use a subagent to review the rate limiter diff against PLAN.md. Check that every requirement is implemented, the listed edge cases have tests, and nothing outside the task's scope changed. Report gaps, not style preferences. ``` One caution from the docs: a reviewer asked to find gaps will usually report some, even when the work is sound, because that is what it was asked to do. Chasing every finding leads to over-engineering, such as extra abstraction layers, defensive code and tests for cases that cannot happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements, and treat the rest as optional. You can also use a Writer/Reviewer split across two sessions, or have one Claude write tests and another write code to pass them. ## What goes wrong, and how do I recover? Correct course early. These controls are built in: - `Esc` stops Claude mid-action and keeps context so you can redirect. - `Esc` twice, or `/rewind`, opens the rewind menu, where you can restore the conversation, the code, or both, or summarize from a selected message. - `/clear` resets context between unrelated tasks. Checkpoints only track changes made through Claude's file-editing tools. Changes made through Bash commands or other processes are not captured, so checkpoints are not a replacement for git. The failure patterns the docs name are worth remembering: - **The kitchen sink session:** unrelated tasks in one context. Fix: `/clear` between them. - **Correcting over and over:** after two failed corrections, `/clear` and write a better first prompt using what you learned. - **The trust-then-verify gap:** a plausible implementation that misses edge cases. Fix: always provide tests, scripts or screenshots. If you cannot verify it, do not ship it. - **The infinite exploration:** an unscoped "investigate". Fix: scope it narrowly or use subagents. ## How does this map to a team process? The same ideas scale from one terminal to a team: nothing is built until the approach is agreed, nothing is done until a check passes, and someone other than the author reviews. Atlas, which runs a team of AI engineers on Claude Code, applies this order with gates: building waits for an approved architecture, a signed-off design and failing tests, and completion is refused until the work is on main or queued for the landing train and the product's rules pass. Every build is also reviewed as it finishes. Atlas does this with its own board and gates; the plan mode, `/goal` and Stop hook features described above are on Atlas's list to build in, so they work without any setup on your side. Until then, if you work alone in the CLI, plan mode, a failing test first and a fresh-context review give you a similar discipline. See the [Atlas home page](https://bridge-terminal.com/atlas/) for how the team version works. ## Conclusion Plan when the change is big or unfamiliar; skip planning when the diff fits in a sentence. Write the spec to a file, run the work in a clean session, and do not accept "done" without a check the agent ran and showed you. Start small: add one runnable check to your next prompt, and move to `/goal` or a Stop hook once you trust the check enough to walk away. ## Questions people ask ### How do I turn on plan mode in Claude Code? Press Shift+Tab until the status bar shows plan mode on, or start the session with claude --permission-mode plan. In plan mode Claude reads files and answers questions, and Claude Code blocks edits until you approve a plan. ### When should I not use plan mode? Skip it when the scope is clear and the change is small, such as a typo, a log line or a rename. The docs suggest that if you could describe the diff in one sentence, skip the plan and ask Claude to do it directly. ### How do I make Claude Code check its own work? Give it a check it can run, such as a test suite, build, linter or screenshot comparison, and ask it to run the check and iterate until it passes. For unattended runs you can set a /goal condition or use a Stop hook that blocks the turn until the check passes. ### Should the same session write and review the code? Better not. A reviewer in a fresh subagent or session sees only the diff and your criteria, so it is not biased by the reasoning that produced the change. Tell it to flag only gaps that affect correctness or the stated requirements. ## About Atlas: Plan, test and review as enforced steps This workflow is plan first, a check that must pass, then review by someone else. Atlas builds that order into its team of AI engineers: building waits for an approved architecture, a signed-off design and failing tests, and every build is reviewed as it finishes. Completion is refused until the work is on main or queued for the landing train and the product's rules pass. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code](https://code.claude.com/docs/en/best-practices) - [Choose a permission mode (Claude Code docs)](https://code.claude.com/docs/en/permission-modes) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Test-First with Claude Code: Failing Tests Before Code](https://bridge-terminal.com/atlas/blog/claude-code-test-first-workflow-failing-tests/) - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) --- # AI Coding Agent Risks and How to Reduce Them > Is an AI coding agent safe? A plain-English guide to what can go wrong, from deleted files to leaked passwords, and the simple controls that lower the risk. Canonical: https://bridge-terminal.com/atlas/blog/ai-coding-agent-risks-what-can-go-wrong/ Last updated: 2026-10-17 Published 17 October 2026 · Plain English · Explainer · 7 min read ## The short version - The main risks of an AI coding agent are unwanted changes, deleted or leaked data, work that looks finished but is not, and being tricked by hostile text it reads. - The agent can only do what it is allowed to do, so most of the risk is managed by deciding in advance what it may touch and what needs a person's yes. - Keep real customer data, live systems and passwords out of the agent's reach until you have watched it work safely on something harmless. - You are responsible for reviewing what an agent proposes, but approval prompts get tiring, so safer set-ups limit the agent's reach instead of relying on careful clicking. - Never skip the way back: a backup you have restored once and a clear plan to undo a release matter more than any promise about the AI. Is an AI coding agent safe to use? Mostly yes, if you decide in advance what it may touch and what needs a person's approval. The real risks are not science fiction. They are ordinary: a wrong change, a deleted file, a leaked password, or code that looks finished but is not. This guide lists what can go wrong, in everyday terms, and the controls that keep each risk small. You do not need to read code to apply them. ## What can actually go wrong with an AI coding agent? An AI coding agent is a program that reads your project, writes changes and runs commands on a computer, much as a junior engineer would. Because it can act, not just chat, its mistakes have consequences. Here are the five that matter most. ### 1. It changes things you did not ask for You ask for a new checkout button. The agent also "tidies" the pricing logic. Nothing crashes, but a discount stops working. This is a common problem and a hard one to notice, because the app still runs. **Keeping it small:** say clearly what is in and out of scope, and ask for a short summary of every change in words you understand. ### 2. It deletes or overwrites something Agents run commands, and some commands remove or replace files. Anthropic's documentation for Claude Code describes an "Accept Edits" mode that automatically approves file edits plus a fixed set of file commands, including ones that remove, move and copy files, for paths in the working folder. That is convenient, and it also means a mistake in that folder does not stop to ask. **Keeping it small:** the agent should work on a copy of the project, with the history saved, so any change can be undone. Ask your engineers one question: "If the agent wrecked this folder right now, how long would it take to get back?" The answer should be minutes. ### 3. It leaks a secret Secrets are passwords, access keys and tokens that unlock your database, payment provider or cloud account. They leak when someone pastes one into a chat, or when one is saved inside the code itself, where many people can see it. **Keeping it small:** do not paste secrets into a chat with an agent unless the tool puts them straight into a secure store. Give the agent separate keys with limited power, and replace any key that was ever exposed. ### 4. It produces work that looks done but is not An agent can write the code, say "all tests pass", and still be wrong, for example because it wrote weak tests or tested the wrong thing. This is a quality risk rather than a security one, and many teams meet it first. **Keeping it small:** do not accept "done" on the agent's word. Ask for evidence: screenshots of the screen working, a list of the test cases and what each one proves, and a second pair of eyes (another agent or a person) reviewing before release. ### 5. It is tricked by text it reads This one sounds odd. Prompt injection is when someone hides instructions inside content the agent reads, such as a web page, a document or a support ticket, hoping the agent will obey them instead of you. Anthropic's security documentation describes it as an attempt to override or manipulate an AI assistant's instructions by inserting malicious text. The same page says that no system is completely immune to all attacks. **Keeping it small:** limit what the agent can reach on the internet, be wary of pointing it at content you did not write, and keep it away from systems it does not need. If it cannot reach your customer data, a trick cannot make it leak that data. ## Why does "ask me first" matter? Most agents have permission settings. They decide which actions the agent may take alone and which need your approval. Anthropic's documentation describes two main modes in Claude Code. In Manual mode, the agent starts with read-only permissions. It asks before it edits files, runs tests or executes commands, and it asks before running a command it cannot fully analyse. A built-in set of read-only commands, such as listing files, runs without asking. In Auto mode, a separate reviewing model checks actions instead of you and blocks the ones it judges unsafe. Your own "always ask" and "never allow" rules still apply. The documentation lists Auto mode as the starting mode for interactive terminal sessions, so check which mode your own set-up uses. ### The approval fatigue problem If an agent asks 200 times a day, people start clicking "yes" without reading. Anthropic's documentation says you are responsible for reviewing proposed code and commands before approving. A safer approach is to cut the number of questions by limiting what the agent can do at all. Two ways the documentation describes: - **Allow and deny rules.** You list things the agent may always do and things it may never do. For example, you can block commands that fetch content from the web. - **Sandboxing.** The agent's commands run in a walled-off space with limits on which files and which network addresses they can reach. That means fewer prompts, and a smaller blast radius if something goes wrong. ## How do I keep the risk low in practice? You do not need to be an engineer to run these checks. They are decisions about your project, and they are yours to make. ### Start with something harmless Let the agent build a prototype, an internal tool or a copy of the project with fake data first. Watch how it behaves. Widen its reach only after it has earned it. ### Separate three worlds - **Experiments:** fake data, nothing at stake. - **Test or staging:** a rehearsal copy of the real thing, with realistic but not real data. - **Production:** the live product and real customers. The agent can work freely in the first, with care in the second, and should reach the third only through a release step a person approves. ### Keep a person on the irreversible decisions Some decisions should never be automatic. A good short list: going live in production, spending money, deleting data, sending anything to the outside world, and dropping part of the scope. If your set-up lets the agent do these alone, change it. ### Make the way back real Before any release, ask three things: 1. Is there a marked point we can return to? 2. Is there a backup of the data, and has anyone actually restored it once to prove it works? 3. If the release changes the database, was that change rehearsed on a copy first? A backup you have never restored is a hope, not a backup. ### Watch the cost as well Risk includes money. An agent left running can use a lot of your plan's allowance, and several agents at once use it faster. A daily limit or budget alert is a simple safety net. ## How does Atlas handle these risks? Atlas is a software team of AI engineers built on Claude Code. You talk to one of them, PA, in plain words, and PA shares the work out to specialists. Some decisions are never made for you: production go-lives, spending, deleting data, sending anything outside, and dropping scope. Releases beyond the Mac follow eight steps: the way back is marked, data is backed up and the backup is proven by restoring it, database changes are rehearsed on that copy, then the release goes out and is checked. Secrets pasted into chat go to a secret store first. An optional daily budget warns at 50% and 80% and pauses the team at 100%. You can read more at [Atlas](https://bridge-terminal.com/atlas/). Atlas does not claim to defend against every attack, and it makes no specific claim about prompt injection. Nothing can promise that, and Anthropic says as much about its own tool. ## A short checklist before you let an agent loose - Is the work on a copy, with history saved? - Does the agent have only the access it needs, and no real customer data yet? - Are secrets kept out of chats and out of the code? - Is "done" backed by evidence, not just a statement? - Does a person approve production releases, spending and deletions? - Have you restored a backup at least once? ## Conclusion AI coding agents are not reckless by nature, and they are not magic. They do what their permissions allow, and they do it fast. Treat one like a new contractor: give it a clear brief, limited keys, a place to work that cannot hurt the business, and a person who signs off on anything that cannot be undone. Do that, and the risks above become small, known and manageable. ## Questions people ask ### Is it safe to use an AI coding agent on my real project? It can be, if you limit what it can reach. Work on a copy with saved history, keep real customer data and passwords out of its reach at first, and have a person approve production releases. ### What is prompt injection in simple terms? It is when someone hides instructions in content an AI reads, such as a web page or document, hoping it obeys them instead of you. Anthropic says no system is completely immune, so limit what the agent can reach. ### Can an AI coding agent delete my files? Yes, if it is allowed to run commands that remove files. In Claude Code's Accept Edits mode, file edits and a fixed set of file commands, including remove, move and copy, are auto-approved for paths in the working folder. Work on a copy with history saved. ### Should I paste passwords or API keys into an AI chat? No, unless the tool sends them straight to a secure store. Use limited-power keys for the agent and replace any key that was ever exposed. ### How do I know the AI's work is actually finished? Ask for evidence rather than a statement: screenshots of working screens, a list of test cases and what each proves, and an independent review before release. ## About Atlas: Keeping the irreversible decisions with a person Atlas never decides production go-lives, spending, deleting data, sending anything outside or dropping scope for you. Releases beyond the Mac mark the way back, back up data and prove the backup by restoring it. Secrets pasted into chat go to a secret store first, and an optional daily budget pauses the team at 100%. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code security](https://code.claude.com/docs/en/security) - [Claude Code: Configure permissions](https://code.claude.com/docs/en/permissions) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Codex GPT-5.5 Retirement: What Your Team Should Check > OpenAI retired GPT-5.5 from Codex for ChatGPT sign-ins on 14 October 2026. Here is what changed, who is affected and what to check before work breaks. Canonical: https://bridge-terminal.com/atlas/blog/codex-gpt-5-5-retirement-what-to-check/ Last updated: 2026-10-17 Published 17 October 2026 · Plain English · What's new · 6 min read ## The short version - On 14 October 2026 at noon PDT (19:00 UTC), OpenAI retired the GPT-5.5 model from Codex for people signed in with a ChatGPT account. - Codex sessions that use an API key, and the OpenAI API itself, are not affected by this retirement. - Anything that still names gpt-5.5, such as team defaults, saved settings, managed configurations, custom agents, scheduled tasks and scripts, needs to be updated. - OpenAI's changelog points users to GPT-6.1 Sol (gpt-6.1-sol) when it is available to their plan and client. - The lasting lesson: keep a list of every place your team chooses an AI model, because makers retire models on their own schedule. If your team uses OpenAI Codex and signs in with a ChatGPT account, the GPT-5.5 model stopped working there on 14 October 2026. OpenAI's changelog says it retired at noon PDT (19:00 UTC) that day. Anything that still asks for that model by name needs a new choice, and OpenAI points to GPT-6.1 Sol as the replacement when your plan and app offer it. This article explains what changed, who is affected, what to check this week, and why model retirements are a routine part of building with AI coding agents. ## What changed in Codex on 14 October 2026? Codex is OpenAI's AI coding agent. Behind every agent sits a "model", the AI system that reads your request and writes the code. Models have names and version numbers, and their makers eventually switch old ones off. OpenAI's Codex changelog, in an entry dated 2026-10-14, says that GPT-5.5 retires from Codex for users signed in with ChatGPT. The time given is noon PDT (Pacific Daylight Time), which is 19:00 UTC. From then on, a request for that model by name is no longer available to those users. The same entry tells people to use GPT-6.1 Sol, written as `gpt-6.1-sol` in settings, "when available to your plan and client". That wording matters. Your plan or app may not offer the replacement, so check what your own account shows before you change anything. ## Who is affected, and who is not? The answer depends on how people sign in to Codex. - **Signed in with a ChatGPT account:** affected. GPT-5.5 is gone from Codex for these users. - **Using an API key:** not affected. An API key is a secret code that lets software talk to a service directly, billed by use, instead of through a person's ChatGPT login. The changelog says the OpenAI API and Codex sessions authenticated with an API key are not affected. So a developer who logs in with a ChatGPT plan and a colleague who runs Codex with an API key can have different experiences on the same day. If something works on one laptop and fails on another, check the sign-in method first. ## What should we check this week? The changelog lists the places where an old model name may be hiding. It says to check anything that still references `gpt-5.5`: 1. **Team-level default model selections.** If your company sets a default model for everyone, that setting needs a new value. 2. **Saved model settings.** Individuals may have chosen a model in their own settings months ago and forgotten. 3. **Admin-managed configurations.** Settings that an administrator controls centrally. 4. **Custom agents.** Specialised helpers your team set up, each of which may name its own model. 5. **Recurring scheduled tasks.** Jobs that run on a timer, often unwatched, and so the likeliest to fail without anyone noticing. 6. **Scripts.** Small automated programs that call Codex and name the model in their instructions. For a non-engineer, the practical move is to ask one question in your team chat: "Does anything we run name GPT-5.5?" Then ask whoever answers to look at the six places above. Scheduled tasks and scripts deserve the most attention, because nobody is watching when they run. ### Where to get reliable details For model names and plan details, rely on OpenAI's own changelog and help pages rather than third-party summaries. Names of models change quickly and secondhand posts can be out of date. ## What else shipped in Codex this month? The retirement is the item with a date, but two other entries are worth a glance. **Codex CLI 0.163.0, 2026-10-15.** The CLI is the command-line version of Codex, which you use by typing in a terminal window. This release added a searchable settings panel (`/config`), and changes to supported settings can apply immediately. You can send a follow-up message while Codex is responding to steer it, and interrupting a turn also stops active Code Mode cells. Independent read-only tools, such as skill, memory and conversation-history lookups, can run in parallel. Fixes include better handling of permissions when you resume a thread. **GPT-6.1 Sol Ultrafast, 2026-10-08.** A mode that speeds up how quickly GPT-6.1 Sol produces text in Codex and ChatGPT Work. The changelog says it is available on Pro $500 and eligible Enterprise and Edu plans, and that it is off by default for Enterprise, so a workspace owner must enable it. That is a decision for a manager, not something every user gets automatically. ## Why do AI models keep being retired? Models are not like software you buy once. They are services that the maker runs, improves and eventually switches off. The pattern is predictable: a newer model arrives, and the old one is given a date. For a team, this creates a hidden dependency. Your work may rely on a model name that someone typed into a settings file a long time ago. When the date passes, the name stops working for the affected users. Three habits reduce the risk: - **Keep one list.** Write down every place your team chooses a model: defaults, agents, schedules, scripts. A shared page is enough. You cannot update what you cannot find. - **Name an owner.** One person watches the maker's changelog and tells the team when a date is announced. - **Test the replacement on real work.** A newer model is not automatically better for your tasks. Run a small, representative piece of work on the new model and compare the result with what you got before. Do not switch every automated job on the same afternoon. ### Does choosing a different tool avoid this? Not by itself. Other tools also add and change models. Claude Code, for example, lets you pick a model, and its changelog shows new ones arriving: version 2.1.293, dated 7 October 2026, added Claude Haiku 5.5. If you compare tools, ask how much notice you get and how many places you have to edit when a model changes. ## What does this mean for budgets and planning? A new default model can change how fast work finishes and how much of your plan's allowance it uses. The changelog entries we read do not say whether GPT-6.1 Sol will cost you more or less, so do not assume either. Watch your own usage for a week after switching, and ask your admin before turning on extras such as Ultrafast mode, which is limited to certain plans. ## How does Atlas relate to this? This news is about Codex, and Atlas does not run on Codex. [Atlas](https://bridge-terminal.com/atlas/) is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session with a written role, and its model and effort are tuned to that role. So this particular retirement does not touch Atlas, but the habit of knowing where your team chooses a model applies to any AI tool. ## Conclusion GPT-5.5 left Codex for ChatGPT sign-ins on 14 October 2026. If your team uses Codex that way, search your defaults, saved settings, managed configurations, custom agents, scheduled tasks and scripts for `gpt-5.5`, and move them to the replacement your plan offers, which OpenAI's changelog gives as GPT-6.1 Sol. Then keep a standing list of where models are chosen, so the next retirement date is a quick check instead of a surprise. ## Questions people ask ### When was GPT-5.5 retired from Codex? OpenAI's Codex changelog says GPT-5.5 retired for users signed in with ChatGPT on 14 October 2026 at noon PDT (19:00 UTC). ### Does the GPT-5.5 retirement affect Codex with an API key? No. The changelog says the OpenAI API and Codex sessions authenticated with an API key are not affected. ### What replaces GPT-5.5 in Codex? OpenAI's changelog says to use GPT-6.1 Sol (gpt-6.1-sol) when it is available to your plan and client. Check what your own account offers. ### What do I need to update after the GPT-5.5 retirement? Check anything that still references gpt-5.5: team default model selections, saved model settings, admin-managed configurations, custom agents, recurring scheduled tasks and scripts. ## About Atlas: Know where your team picks its AI model This news concerns Codex, and Atlas does not run on it: Atlas is a team of AI engineers built on Claude Code, with model and effort tuned to each engineer's role. The lesson still carries over: know which model each role uses. — https://bridge-terminal.com/atlas/ ## Sources - [OpenAI Codex changelog (GPT-5.5 retirement, CLI 0.163.0, Ultrafast)](https://learn.chatgpt.com/docs/changelog) - [Claude Code changelog](https://code.claude.com/docs/en/changelog) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [How to Brief an AI Coding Agent: A Plain-English Guide](https://bridge-terminal.com/atlas/blog/how-to-brief-ai-coding-agent-plain-english/) - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) --- # Claude Code Permissions: Allow, Deny Rules and Modes > Set up Claude Code permissions that hold: how allow, ask and deny rules are ordered, which mode to pick, and the Bash rule traps that let commands slip through. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-permissions-allow-deny-rules/ Last updated: 2026-10-16 Published 16 October 2026 · Technical · How-to · 6 min read ## The short version - Claude Code checks deny rules first, then ask, then allow, and the first match wins, so an allow rule can never carve an exception out of a deny rule. - Pick a permission mode for the kind of work: plan to explore, acceptEdits to iterate on code you review, dontAsk with an exact allowlist for CI, and bypassPermissions only inside an isolated container or VM. - A Bash deny rule such as Bash(git push *) stops the usual form of a command but not variants like git -C . push, so treat it as a guardrail, not a security boundary. - Put shared rules in .claude/settings.json, personal ones in .claude/settings.local.json, and block secrets with Read deny rules; add the sandbox when you need OS-level enforcement. How do you set up Claude Code permissions so the agent can work without asking about every command, yet cannot touch what it should not? Write a short set of allow rules for the commands you trust, deny rules for what must never run, and pick a permission mode that fits the task. The part that trips people up is how the rules are matched, so this guide spends most of its time there. Everything below comes from the Claude Code documentation on permissions, permission modes and settings. Check the docs for your installed version, because defaults change between releases. ## How do Claude Code permission rules work? A rule is either `Tool` or `Tool(specifier)`. A bare tool name matches every use of the tool. A specifier narrows it: | Rule | Effect | | :- | :- | | `Bash` | All Bash commands | | `Bash(npm run build)` | Exactly that command | | `Read(./.env)` | Reading `.env` in the current directory | | `WebFetch(domain:example.com)` | Fetches to that host | There are three kinds of rule: allow (run without asking), ask (always prompt) and deny (never run). They are evaluated in a fixed order: deny, then ask, then allow. The first match decides, and specificity does not change that. This has a consequence people miss. A broad `Bash(aws *)` deny blocks every matching call, even if you also wrote a narrower `Bash(aws s3 ls)` allow. You cannot punch a hole in a deny. The same goes for ask over allow: a matching ask rule prompts even when a more specific allow also matches. Deny also wins across files. If user settings allow something and project settings deny it, it is blocked. ## Where do the rules live? Settings are read from several places. Highest precedence first: 1. Managed settings (set by your organization) 2. Command line, such as `claude --settings` 3. `.claude/settings.local.json` (you, this project) 4. `.claude/settings.json` (everyone on the project, checked in) 5. `~/.claude/settings.json` (you, every project) Commit the rules the whole team should share to `.claude/settings.json`. Keep personal habits in the local file. You can inspect and edit the live rules with `/permissions`. ## A starting configuration This lets Claude run npm scripts and commit, while refusing a push: ```json { "permissions": { "allow": [ "Bash(npm run *)", "Bash(git commit *)" ], "deny": [ "Bash(git push *)" ] } } ``` Add secrets protection with Read deny rules, which use gitignore-style patterns: ```json { "permissions": { "deny": [ "Read(./.env)", "Read(./secrets/**)" ] } } ``` Use `Edit(...)` rules for edit restrictions rather than rules written for other tools, and confirm with `/permissions` that the rule behaves as you expect. ## How do Bash wildcards match? A `*` in a Bash rule matches any text, including spaces, and can sit anywhere in the rule. Four details decide whether your rule does what you think: - The space before a trailing `*` is part of the rule. `Bash(ls *)` matches `ls -la` but not `lsof`; `Bash(ls*)` matches both. - `Bash(npm run build)` with no `*` matches only that exact command, so `npm run build --watch` is not covered. - Everything before the first `*` is matched as written. `Bash(git log *)` allows only `git log`, while `Bash(git *)` allows every git command. Avoid putting a `*` before the subcommand in an allow rule, as in `Bash(git * main)`. - Shell operators are understood. `Bash(safe-cmd *)` does not permit `safe-cmd && other-cmd`; each subcommand must match on its own. The `:*` suffix is an equivalent way to write a trailing wildcard, so `Bash(ls:*)` equals `Bash(ls *)`. ## Why a Bash deny rule is not a security boundary A Bash rule matches the command text Claude writes. It does not match the same program invoked another way. The documentation lists what slips past: | Rule | Stops | Does not stop | | :- | :- | :- | | `Bash(curl *)` | `curl https://example.com` | `/usr/bin/curl ...`, `sh -c 'curl ...'` | | `Bash(rm *)` | `rm -rf build/` | `/bin/rm -rf build/`, `bash -c 'rm -rf build/'` | | `Bash(git push *)` | `git push origin main` | `git -C . push origin main` | Rules that try to constrain arguments are even more fragile. `Bash(curl http://github.com/ *)` will not match `curl -X GET http://github.com/...`, an `https` URL, a redirect, or a URL held in a variable. Likewise, Read and Edit deny rules cover Claude's built-in file tools and recognised file commands such as `cat` and `sed`. They do not cover a Python or Node script that opens files itself. For enforcement that applies to every process, enable the sandbox, which restricts shell commands at the operating-system level. The docs recommend using permissions and the sandbox together. If you need a hard block with custom logic, a PreToolUse hook is the next layer. A matching deny or ask rule still applies even if a hook returns "allow", so hooks cannot weaken your rules. ## Which permission mode should you use? Rules say what is allowed. The mode sets how much runs without a prompt. The documented modes: | Mode | Runs without asking | Best for | | :- | :- | :- | | `default` (shown as Manual) | Reads only | Sensitive work, reviewing every action | | `acceptEdits` | Reads, file edits, common filesystem commands such as `mkdir`, `touch`, `mv`, `cp` | Iterating on code you are reviewing | | `plan` | Reads; edits blocked until you approve a plan | Exploring before changing anything | | `auto` | Actions reviewed by a background classifier instead of by you | Long tasks, fewer prompts | | `dontAsk` | Reads plus pre-approved tools; everything else denied | Locked-down CI and scripts | | `bypassPermissions` | Everything, with few exceptions | Isolated containers and VMs only | Switch inside a session with Shift+Tab, or start with a flag: ```bash claude --permission-mode plan ``` To change the default for a project, set `defaultMode` in a settings file. On Claude Code v2.1.283 or later, auto mode is the built-in starting mode for interactive terminal and VS Code sessions; on earlier versions it is the starting mode only on Pro, Max and Team plans. So if you expect prompts and do not see them, check which mode you started in. ### Plan mode for risky changes Plan mode is the cheap way to find out whether Claude understood the task. Claude reads the code and proposes a plan, and edits wait until you approve it. Use it before refactors, migrations and anything touching several modules. ### dontAsk for CI In a pipeline nobody can answer a prompt. Pair `dontAsk` with an exact allowlist: ```bash claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read" ``` Anything outside the list is denied rather than hanging. ## Gate subagents, MCP tools and parameters Rules reach beyond Bash and files: - `mcp__puppeteer__*` matches every tool from one MCP server. - `Agent(Explore)` or `Agent(my-custom-agent)` in `deny` disables a specific subagent. ## A practical setup checklist 1. Start a new project in `plan` or Manual mode and watch which prompts repeat. 2. Turn the repeats into narrow allow rules, such as `Bash(npm run *)`, and commit them in `.claude/settings.json`. 3. Add deny rules for secrets (`Read(./.env)`) and for commands you never want, such as `Bash(git push *)`, remembering their limits. 4. Add `ask` rules for actions you want a human on, such as deploys. 5. Turn on the sandbox if the agent runs untrusted code or you need enforcement that does not depend on command text. 6. Review the result with `/permissions`. ## Conclusion Permissions work best as layers: narrow allow rules for speed, deny rules for guardrails, a mode matched to the task, and the sandbox or a hook where a hard guarantee matters. Remember the evaluation order, never rely on a Bash deny alone, and keep `bypassPermissions` for throwaway containers. If you run several agents at once, the same rules apply to each session, so a shared `.claude/settings.json` keeps them consistent. ## Questions people ask ### What is the order of allow, ask and deny rules in Claude Code? Rules are evaluated deny first, then ask, then allow, and the first match decides. A narrower allow rule cannot override a broader deny rule, and a deny in one settings file wins over an allow in another. ### Does a Bash deny rule like Bash(git push *) fully block pushes? No. It stops the usual form but not variants such as git -C . push or running the program through sh -c. Treat it as a guardrail, and use the sandbox or a PreToolUse hook for stronger enforcement. ### Which Claude Code permission mode should I use in CI? dontAsk with an exact allowlist, for example --permission-mode dontAsk with --allowedTools "Bash(npm test)" "Read". Anything not on the list is denied instead of waiting for a prompt. ### How do I stop Claude Code reading my .env file? Add a Read deny rule such as Read(./.env) or Read(./secrets/**) to your settings. It covers Claude's file tools and recognised file commands, but not a script that opens files itself, so enable the sandbox for that. ### Where should I put Claude Code permission rules for a team? Put shared rules in .claude/settings.json and commit it. Keep personal preferences in .claude/settings.local.json or in your user settings in ~/.claude/settings.json. ## About Atlas: Approvals for the decisions that matter, not every command Permission rules decide what one Claude Code session may run. Atlas runs each engineer as its own Claude Code session and keeps a separate layer on top: production go-lives, spending, deleting data, sending anything outside and dropping scope are never decided for you, and secrets pasted into chat go to a secret store first. — https://bridge-terminal.com/atlas/ ## Sources - [Configure permissions - Claude Code Docs](https://code.claude.com/docs/en/permissions) - [Choose a permission mode - Claude Code Docs](https://code.claude.com/docs/en/permission-modes) - [Settings files and precedence - Claude Code Docs](https://code.claude.com/docs/en/settings) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code Sandbox: Limit Files and Network for Bash](https://bridge-terminal.com/atlas/blog/claude-code-sandbox-bash-files-network/) - [Claude Code Headless in CI: -p Mode and Safe Permissions](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/) - [Claude Code Mods: What They Are and the Risks to Check](https://bridge-terminal.com/atlas/blog/claude-code-mods-what-they-are-risks/) --- # How to Brief an AI Coding Agent: A Plain-English Guide > How to brief an AI coding agent without writing code: what to put in the request, how to define "done", and the common mistakes that cost you rework. Canonical: https://bridge-terminal.com/atlas/blog/how-to-brief-ai-coding-agent-plain-english/ Last updated: 2026-10-16 Published 16 October 2026 · Plain English · How-to · 7 min read ## The short version - A good brief says what should happen, where it happens, what must not change, and how you will know it works. - The most useful thing to add is a check that gives a clear pass or fail: example inputs with expected answers, a design to compare against, or a test. - Vague requests like 'make it look better' or 'fix the login bug' lead to rounds of corrections; a symptom plus a description of 'fixed' does not. - For bigger features, ask the agent to interview you and write a short spec (a written description of what will be built) before it builds anything. - If you have corrected the agent twice on the same point, start a fresh conversation with a better brief instead of correcting a third time. If you want to know how to brief an AI coding agent, the short answer is this: describe the result you want in business terms, point to where it lives, say what must not change, and say how you will know it works. The agent can infer a lot, but it cannot read your mind. Anthropic's guide to Claude Code puts it this way: Claude "can infer intent, but it can't read your mind." You do not need to write code to do this. You need to be as clear as you would be with a new contractor on their first day. ## Why does the brief matter so much? An AI coding agent works fast and does what it understood, not what you meant. If the request is vague, it makes choices for you, and you find out later. Anthropic's guide says it plainly: "The more precise your instructions, the fewer corrections you'll need." OpenAI's guidance for Codex, its coding agent, makes a similar point. A useful prompt, it says, preserves important constraints and says how to verify the change. Two words matter most to non-coders: constraints (what must stay the same) and verification (how you will know it works). We cover both below. ## What should a good brief include? Think of four parts. You can write each in a sentence or two. ### 1. The outcome, in your words Say what a person should be able to do, or what should be different. "A customer who forgets their password can get a reset email and set a new one" is a good outcome. "Add password stuff" is not. ### 2. Where it happens Name the screen, the page, the report or the part of the product. If you can, attach a screenshot. Claude Code lets you paste images into the prompt, and Codex's guidance covers working from images too. Pointing at things saves the agent from guessing. If something similar already exists, say so. Anthropic's example contrasts "add a calendar widget" with a request that tells Claude to look at how the existing widgets on the home page are built and follow that pattern. For you, that might be: "make the new invoices page work like the existing orders page." Codex's guidance adds one point about pictures: an image shows what something looks like, but you still need to describe behaviour it does not show, such as what happens on hover or what counts as valid input. ### 3. What must not change Constraints are the guard rails. Examples: - "Do not change what customers see on the checkout page." - "Keep the fix small." - "Do not add new paid services." - "Use the tools we already use." OpenAI's bug-fix example for Codex includes lines like "Do not change the API shape" and "Keep the fix minimal". This is where your knowledge of the business is worth the most, because the agent cannot know which parts are sensitive. ### 4. How you will know it works This is the part most people skip. More on it next. ## How do I tell the agent what "done" means? Give it something that says pass or fail. Anthropic's guide has a section titled "Give Claude a way to verify its work". Its reasoning: the agent stops when the work looks done. Without a check it can run, "looks done" is the only signal it has, and you become the person who has to catch every mistake. You can supply a check in plain terms: - **Examples with answers.** "A discount code of SAVE10 takes 10% off. An expired code shows the message 'This code has expired'. An empty code does nothing." - **A picture of the goal.** "Here is the design. Take a screenshot of the result and list the differences." - **A story to replay.** "A new user signs up, adds an item, pays, and gets a receipt email. That whole path must work." Then ask for evidence, not reassurance. Anthropic suggests having the agent show the test output, the command it ran and what came back, or a screenshot, rather than just saying it succeeded. "It works" is a claim. A passing test and a screenshot are proof you can look at. If you cannot say how you would check a piece of work, slow down. Anthropic lists this among its common failure patterns: if you can't verify it, don't ship it. ## Weak briefs and better briefs Here are three everyday swaps, adapted from the examples in Anthropic's guide. **"Fix the login bug."** Better: "Customers report that login fails after they have been away for a while. Write a test that shows the problem first. Then fix it, and show me it no longer happens." This gives the symptom, asks for the problem to be reproduced, and defines fixed. **"Make the dashboard look better."** Better: "Here is the design from our designer. Make the dashboard match it, take a screenshot, and tell me what still differs." **"Add tests."** Better: "Test what happens when a customer is logged out and tries to open their invoices. Avoid fakes where you can." That gives scope, scenario and a preference in one line. ("Mocks", in Anthropic's wording, are stand-ins for real parts of the system.) Notice what is missing from the better versions: jargon. Every one is something a product owner or analyst can write. ## Should I plan first or let it start building? For anything beyond a small tweak, plan first. Anthropic recommends separating research and planning from building, because letting the agent jump straight to code can produce something that solves the wrong problem. Codex's guidance also suggests asking for a plan before editing on multi-step tasks, and working through larger changes in milestones. A simple rule from Anthropic: if you could describe the change in one sentence, skip the plan. Fixing a typo or renaming a label does not need one. A new payment option does. For bigger features, there is a handy trick: ask the agent to interview you. Anthropic suggests starting with a short description and asking Claude to question you about the hard parts, including technical choices, how the screen should behave, edge cases and trade-offs, and then to write a spec. A spec is just a written description of what will be built. The most useful specs, Anthropic says, are self-contained, state what is out of scope, and end with a step that proves the feature works from start to finish. Your answers in that interview are your real contribution. You know the customers and the rules; the agent knows how to turn them into software. ## What goes wrong, and how do I spot it early? These problems come up again and again. - **Plausible but incomplete work.** The result looks right but misses the awkward cases, like an empty form or an expired card. Cure: examples that include the awkward cases. - **Correcting again and again.** Anthropic's advice is that after two failed corrections on the same point, you should clear the conversation and write a better opening request that includes what you learned. A clean start with a better brief almost always beats a long thread of patches. - **Unrelated requests in one conversation.** The agent's working memory, which Anthropic calls the context window, holds everything said and every file read. Performance degrades as it fills. Start a new conversation for a new topic. - **Open-ended "investigate this" requests.** Without limits, the agent may read hundreds of files and fill that working memory. Say what you want to learn and where to look. Vague is not always wrong. If you are exploring ("what would you improve on this page?"), a loose question can surface things you would not have thought to ask. Just do not expect a precise result from it. ## What does this mean for my role? Your job moves from describing tasks to deciding what good looks like. That means writing the examples, naming the constraints, approving plans and looking at the evidence. Product owners, analysts and testers already have these skills. It also means you should decide the things an agent should not decide alone: spending money, going live, deleting data, dropping features. Keep those with you whatever tool you use. ## Where Atlas fits Atlas is a team of AI engineers built on Claude Code. You brief one of them, PA, in plain words, and PA shares the work with specialists. Its gates help a brief hold: building waits for an approved architecture, a signed-off design and failing tests, and "done" is refused until the work is on main or queued to land and a screen has its test cases and screenshots. If writing an issue list is the hard part, you can record a call or walkthrough instead, and Atlas lists the issues for you to review before anything is fixed. Atlas does not decide production go-lives, spending or deleting data for you. You can read more at [Atlas](https://bridge-terminal.com/atlas/). ## Conclusion A good brief is short: the outcome, where it happens, what must not change, and how you will know it works. Add examples, ask for evidence, plan first for anything big, and restart with a sharper brief rather than patching a muddled one. You do not need to learn to code to do any of this. You need to be clear about what you want and honest about what you can check. ## Questions people ask ### How do I write a good prompt for an AI coding agent if I can't code? Describe the outcome in business terms, say where it happens, list what must not change, and give examples of what working looks like. Ask the agent to show evidence, such as test results or a screenshot, rather than just saying it worked. ### How long should a brief for an AI coding agent be? Short but specific. A few sentences covering the outcome, where it happens, the limits and a check are a good start. For bigger features, ask the agent to interview you and write a spec (a written description of what will be built) instead of writing everything up front. ### Should the AI make a plan before it builds? For anything beyond a small change, yes. Anthropic recommends separating planning from building, and OpenAI's Codex guidance suggests planning first for multi-step tasks, so you can correct the approach before building starts. If you could describe the change in one sentence, you can skip the plan. ### What if the agent keeps getting it wrong? After two failed corrections on the same point, start a fresh conversation with a better brief that includes what you learned. Anthropic says a clean session with a better prompt almost always beats a long one full of corrections. ## About Atlas: Briefing PA in plain words, with gates behind it In Atlas you brief PA, the project assistant, in plain words, and the work is shared with specialist AI engineers. Building waits for an approved architecture, a signed-off design and failing tests, and work is not called done until it is on main or queued to land and screens have test cases and screenshots. You can also record a call instead of writing an issue list, and nothing is fixed until you approve. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code (Anthropic)](https://code.claude.com/docs/en/best-practices) - [Prompting Codex (OpenAI)](https://learn.chatgpt.com/docs/prompting) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Claude Code Idle Compaction: Cheaper Breaks, Same Session > Claude Code 2.1.299 (14 Oct 2026) now compacts very long idle chats before the one-hour cache runs out. What changed, the trade-off, and how to turn it off. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-idle-compaction-prompt-cache/ Last updated: 2026-10-22 Published 16 October 2026 · Plain English · What's new · 6 min read ## The short version - On 14 October 2026 Claude Code 2.1.299 added idle compaction: a conversation of 200,000 tokens or more that sits idle for about 54 minutes is summarised before its one-hour prompt cache expires. - The aim is that your first message after a long break does not make the AI reprocess the whole conversation. The changelog gives no figure for the saving. - It only applies to very long conversations (200,000 tokens or more). You can change that minimum or turn the feature off; both need version 2.1.290 or later. - Compaction replaces the conversation with a shorter version, so small details can be lost. Keep important decisions in written project files, not only in chat. - Atlas's engineers are Claude Code sessions on your own plan. Managing this and showing cache and idle-time costs per engineer is on Atlas's list to build in, so it works without any setup on your side; until then, Claude Code's own compaction settings apply. Claude Code, Anthropic's coding agent, now shrinks a very long conversation on its own if you leave it idle for about 54 minutes. This is called idle compaction, and it arrived in Claude Code version 2.1.299 on 14 October 2026. The goal is simple: when you come back from a break, your next message should not make the AI reprocess a huge conversation from scratch. If you manage a team that uses AI coding agents, this is a small change that can affect how quickly you use up your plan. Here is what it is, what changed, and what to do about it. ## What is idle compaction in Claude Code? You need two ideas to understand it. **Context** is everything the AI is holding in mind during a session: your instructions, the files it has read, its own earlier answers. It is measured in tokens, which are small chunks of text. A very long working session can pass 200,000 tokens. **Prompt caching** is a shortcut. Each time you send a message, the AI has to process the whole context again. Caching lets the provider remember the part it already processed, so the repeat is cheaper. Anthropic's documentation says reading from this cache costs 0.1 times the normal input price for most models, and less for some newer ones. The catch is that the cache does not last. Anthropic's API documentation says the default lifetime is 5 minutes, with an optional 1-hour lifetime at additional cost. The Claude Code changelog entry for this change refers to a one-hour prompt cache. Once the cache has expired, the next message has to process everything again at the normal input price. **Idle compaction** is Claude Code's answer. According to the changelog, a conversation of 200,000 tokens or more that has been idle for about 54 minutes is compacted before its one-hour prompt cache expires. Compacting means the conversation is replaced by a shorter summary of itself. The next message then starts from something small instead of reprocessing the whole thing. ## What exactly changed, and when? The change is listed under Claude Code 2.1.299, dated 14 October 2026. The changelog says it was added "in the terminal". The details: - It applies to conversations of 200,000 tokens or more. - It triggers after about 54 minutes idle, a few minutes before the one-hour cache runs out. - You can change the 200,000-token minimum with an environment variable (a named setting your computer passes to the program) called `CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS`. - You can turn the feature off by setting `"idleCompaction": false` in Claude Code's settings file, `settings.json`. - Both of these need version 2.1.290 or later. The changelog does not give a saving in dollars or percent, and neither will we. It states the purpose: so "your next message doesn't reprocess it all." ## Why does it matter if I don't write code? Because the cost of an AI agent depends not only on how much it does, but also on how long its memory gets and how often it has to be rebuilt. Picture a product owner who spends the morning with an agent working through a large feature. The conversation grows long. They go to a one-hour planning meeting. When they return and type "continue with the checkout page", one of two things happens: 1. **Without idle compaction:** the cache has expired, so the whole long conversation is processed again at the normal input price. On a subscription plan, that should mean a bigger bite out of your usage limit. On a pay-per-use account, a bigger bill. 2. **With idle compaction:** the conversation was already shrunk while you were away, so the first message back has much less to process. For short sessions the effect is small, which is why the feature only starts at 200,000 tokens. It matters most for people who keep one very long session open all day. ## What is the downside? A summary is shorter than the original, so something can be lost. The agent may forget a small detail you mentioned two hours ago, such as a naming rule, an edge case, or a decision about what not to build. Compaction itself is not new to Claude Code. What is new is that it can now happen while you are away, so you may not see it happen. You will come back to a session that is a little more condensed than the one you left. Three habits make this harmless: - **Write decisions down.** Put rules and decisions in a project file the agent reads at the start, instead of relying on something said in chat. - **Brief clearly.** A good written brief survives any summary better than a vague chat. - **Start fresh for new work.** If you are moving to a different task, a new session is cleaner than a very long one, whatever compaction does. ## Should I turn idle compaction off? For most people, probably not. It is on by default, and it only touches very long, idle conversations. Consider turning it off, or raising the minimum, if: - you work in long sessions where small details matter a lot, and you would rather decide yourself when to compact; - you are doing a careful, step-by-step review where you want the full original record kept in the conversation; - you already start a fresh session for each piece of work, so you rarely reach 200,000 tokens anyway. The engineer who sets this up only needs the settings file or the environment variable named above. It does not need a change to your product's code. ## Other things in the same release window Idle compaction was not the only change in the last two weeks. A few others from Anthropic's changelog are worth a line for managers: - **Hooks can now fail safe (8 October 2026, version 2.1.295).** Hooks are small automatic checks that run around the agent's actions. A command or HTTP hook can now be set with `onFailure: "block"`, so that if the hook cannot start, times out, or exits with an unexpected code, the action is blocked instead of let through. - **Tool permission rules got stricter (14 October 2026, version 2.1.299).** An allow rule for one connected tool server (an MCP server) now reaches only the server it names. Previously, a rule such as `mcp__a` could also allow a server named `a__b` or `a_`. If your team wrote rules by hand, check them. - **Retry limit for unattended runs (15 October 2026, version 2.1.301).** A new setting lets an unattended run stop waiting when a usage limit resets too far away. - **More detail in usage reporting (14 October 2026, version 2.1.300).** The OpenTelemetry `api_request` event, a standard way to send usage data to monitoring tools, now splits cache writes by lifetime (5-minute and 1-hour). ## Does Atlas handle this? Not yet. Atlas is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session, running on your own Claude plan, so idle engineers sit on the same plan limits as everything else. Managing the cache, showing idle-time costs per engineer and choosing when a session is compacted are on Atlas's list to build in, so they work without any setup on your side; until then, compaction follows the Claude Code settings described above. What it does around cost is an optional daily budget that warns at 50% and 80% and pauses the team at 100%. Engineers also checkpoint their work, so a restart resumes where they stopped. You can read more on the [Atlas home page](https://bridge-terminal.com/atlas/). ## The bottom line Idle compaction is a quiet, sensible fix for a real problem: long sessions that go cold. It is on by default, it only affects conversations of 200,000 tokens or more, and you can tune or disable it. The practical advice has not changed. Keep important decisions in written files, start new sessions for new work, and remember that a summary is only a summary. If your team works in long sessions, ask the engineer who owns your setup to confirm the version is 2.1.299 or later and to decide whether the default suits you. ## Questions people ask ### What is idle compaction in Claude Code? It is a feature added on 14 October 2026 in Claude Code 2.1.299. A conversation of 200,000 tokens or more that is idle for about 54 minutes is compacted, meaning replaced by a shorter summary, before its one-hour prompt cache expires. ### How do I turn off idle compaction in Claude Code? Set "idleCompaction": false in settings.json. You can instead change the 200,000-token minimum with the environment variable CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS. Both need Claude Code 2.1.290 or later. ### Why can a Claude Code conversation cost more after a break? Anthropic's docs say the prompt cache lasts 5 minutes by default, or 1 hour as a paid option. Once it expires, the next message has to process the whole conversation again at the normal input price instead of the much lower cache-read price. ### Can idle compaction make Claude forget things? Yes, in principle. Compaction swaps the conversation for a shorter summary, so small details can be lost. Keep key rules and decisions in written project files so they survive. ## About Atlas: Long sessions, idle engineers and your plan's limits Atlas runs each engineer as its own Claude Code session on your Claude plan, so long, idle sessions count against the same limits. Managing compaction and showing cache costs is on Atlas's list to build in, so it works without any setup on your side; until then, Claude Code's own settings handle compaction. It does offer an optional daily budget that warns at 50% and 80% and pauses at 100%, and engineers checkpoint so a restart resumes where they stopped. — https://bridge-terminal.com/atlas/ ## Sources - [Claude Code changelog (Anthropic)](https://code.claude.com/docs/en/changelog) - [Prompt caching (Anthropic API docs)](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [Claude Fast Mode for Opus 5.5: Cost and When It Pays](https://bridge-terminal.com/atlas/blog/claude-fast-mode-opus-5-5-cost/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) --- # Claude Code Skills: Turn Repeated Prompts into Commands > Claude Code skills turn a checklist you keep pasting into a reusable /command. Covers SKILL.md, arguments, shell injection and tool permissions. Canonical: https://bridge-terminal.com/atlas/blog/claude-code-skills-reusable-commands/ Last updated: 2026-10-22 Published 15 October 2026 · Technical · Explainer · 6 min read ## The short version - A Claude Code skill is a folder with a SKILL.md file; create one when you keep pasting the same checklist or when a CLAUDE.md section has turned into a procedure. - A skill body loads only when it is used, so long procedures cost little context compared with CLAUDE.md, which is always loaded. - Frontmatter controls who can start a skill: disable-model-invocation keeps risky actions like deploys manual, and allowed-tools pre-approves the commands you list for that turn without restricting other tools. - Shell injection with !`command` puts live data such as a git diff into the prompt before Claude sees it, but a failing command aborts the whole invocation. context: fork runs the skill in a subagent. - Old .claude/commands/ files still work; commands and skills have been merged, so new work should use the skills layout. If you keep pasting the same instructions into Claude Code, make it a skill. A skill is a directory with a `SKILL.md` file; Claude can load it when it is relevant, or you can run it yourself as `/skill-name`. This article shows how to write one, pass arguments, inject live data, limit permissions and share it with your team. Everything below follows the Claude Code documentation on skills, linked at the end. ## What is a Claude Code skill? A skill is a Markdown file with YAML frontmatter between `---` markers, followed by instructions. The frontmatter must start on the first line of the file, or it is not read. The key property is when the body loads: unlike CLAUDE.md content, a skill's body loads only when it is used. That is the whole design argument. CLAUDE.md holds facts that must always be in context: build commands, conventions, where things live. Procedures, such as "how we cut a release" or "how we review a migration", belong in skills, where they cost little until needed. If you are deciding what goes where, see [CLAUDE.md best practices](https://bridge-terminal.com/atlas/blog/claude-md-best-practices-project-instructions/). ### Are skills the same as slash commands? Custom commands have been merged into skills. A file at `.claude/commands/deploy.md` and one at `.claude/skills/deploy/SKILL.md` both create `/deploy`, and existing command files keep working. If a skill and a command file share a name, the skill wins. Skills add a directory for supporting files, frontmatter that controls who can invoke them, and automatic loading by Claude. Command files accept the same frontmatter, except `name` and `paths`. ## Where do skills live? Location decides who gets the skill: | Location | Path | Scope | | :- | :- | :- | | Enterprise | `.claude/skills/` inside the managed settings directory | Machines where your organization deploys it | | Personal | `~/.claude/skills//SKILL.md` | All your projects | | Project | `.claude/skills//SKILL.md` | This repository | | Nested | `/.claude/skills//SKILL.md` | Sessions in or below that subdirectory | | Plugin | `/skills//SKILL.md` | Where the plugin is enabled, invoked as `/plugin-name:skill-name` | When names collide, enterprise beats personal, and personal beats project. Commit project skills to the repository and the whole team gets them. Nested skills load the first time Claude reads or edits a file in that subdirectory, which suits monorepos. ## Your first skill: summarize and review a diff Create `.claude/skills/diff-review/SKILL.md`: ```yaml --- description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff. allowed-tools: Bash(git diff *) --- ## Current changes !`git diff HEAD` ## Instructions Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes. ``` Two things happen here. The `description` tells Claude when to load the skill, so write it as "what it does, plus when to use it". The combined `description` and `when_to_use` text is truncated at 1,536 characters in the skill listing, so put the key use case first. The line starting with `!` followed by a backtick-wrapped command is shell injection. Claude Code runs `git diff HEAD` before Claude sees the skill and replaces the placeholder with the output. Claude sees the real diff, not an instruction to go and fetch it. The inline form is recognized only at the start of a line or after whitespace. Edits to existing skill files take effect in the current session without a restart; if you create a brand-new top-level skills directory mid-session, run `/reload-skills`. Two rules from the docs matter in practice. First, if an injected command fails, the whole invocation aborts and Claude never sees the skill. Any non-zero exit counts, apart from exit code 1 from search and comparison commands, so append `|| true` to commands that may fail. Second, injected commands are checked against your permission rules and do not prompt. A deny match aborts, and outside auto mode anything other than an allow also aborts, which is why the example pre-approves the command with `allowed-tools`. For multi-line commands, use a fenced block opened with three backticks and a `!`. ## How do I pass arguments to a skill? `$ARGUMENTS` expands to everything after the skill name: ```yaml --- name: fix-issue description: Fix a GitHub issue disable-model-invocation: true --- Fix GitHub issue $ARGUMENTS following our coding standards. ``` Running `/fix-issue 123` makes Claude receive "Fix GitHub issue 123 following our coding standards." For several values, use `$ARGUMENTS[N]` or the shorthand `$0`, `$1`, `$2` (indexes start at 0): ```yaml --- name: migrate-component description: Migrate a component from one language to another --- Migrate the $0 component from $1 to $2. Preserve all existing behavior and tests. ``` Quote multi-word values: `/my-skill "hello world" second` makes `$0` equal `hello world`. If the skill text contains no placeholder, Claude Code appends `ARGUMENTS: ` to it instead. You can also declare named positional arguments in an `arguments` field and use `$issue` or `$branch` in the body, and add `argument-hint` (for example `[issue-number]`) for autocomplete. Other substitutions include `${CLAUDE_SKILL_DIR}`, the directory containing `SKILL.md`, which is useful for pointing at a bundled script. To write a literal dollar sign before a digit, escape it as `\$1.00`. ## Who can run a skill: you, Claude, or both? Two frontmatter fields control invocation: | Frontmatter | You can invoke | Claude can invoke | | :- | :- | :- | | (default) | Yes | Yes | | `disable-model-invocation: true` | Yes | No | | `user-invocable: false` | No | Yes | Use `disable-model-invocation: true` for anything with side effects: deploys, commits, messages sent outside. You do not want the model deciding on its own that now is a good time to deploy. Use `user-invocable: false` for background knowledge Claude should pull in on its own but that makes no sense as a command; it hides the skill from the `/` menu. You can also restrict skills through permission rules. Deny the Skill tool in `/permissions` to disable all of them, or use rules such as `Skill(commit)` for an exact match and `Skill(deploy *)` for a prefix match to allow or deny specific ones. ## How do I pre-approve tools for a skill? `allowed-tools` lets Claude use the listed tools without prompting during the turn that invokes the skill: ```yaml --- name: commit description: Stage and commit the current changes disable-model-invocation: true allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) --- ``` Note the limits stated in the docs: it does not restrict other tools, which still follow your normal permission settings, and the grant clears when you send your next message. The value can be space- or comma-separated, or a YAML list. If you want to remove tools instead, `disallowed-tools` takes them out of Claude's pool while the skill is active. For unattended runs, read [Claude Code headless in CI](https://bridge-terminal.com/atlas/blog/claude-code-headless-ci-permissions/) before relying on any of this. ## How do I keep a skill from bloating context? Keep `SKILL.md` under 500 lines and move detail into supporting files that Claude loads when needed: ```text my-skill/ ├── SKILL.md (required - overview and navigation) ├── reference.md (detailed API docs - loaded when needed) ├── examples.md (usage examples - loaded when needed) └── scripts/ └── helper.py (utility script - executed, not loaded) ``` Reference the files from `SKILL.md` so Claude knows they exist. A script that is executed rather than read costs no context for its source, which makes scripts a good home for deterministic steps such as formatting a report. ## Running a skill in a subagent Add `context: fork` and the skill content becomes the prompt for a new subagent. That subagent does not see your conversation history, so the instructions must be self-contained and contain an explicit task; guidelines alone produce no output: ```yaml --- name: pr-summary description: Summarize changes in a pull request context: fork agent: Explore allowed-tools: Bash(gh *) --- ## Pull request context - PR diff: !`gh pr diff` - PR comments: !`gh pr view --comments` - Changed files: !`gh pr diff --name-only` ## Your task Summarize this pull request... ``` The `agent` field picks the subagent type: `Explore`, `Plan`, `general-purpose` (the default) or a custom agent. Forked skills run in the background by default, so you can keep working; set `background: false` to wait for the result. In `-p` and SDK mode the result is waited for anyway. Forking keeps noisy exploration out of your main context. For when splitting work is worth it, see [Claude Code subagents](https://bridge-terminal.com/atlas/blog/claude-code-subagents-when-to-split-work/). Skills can also set `model` and `effort` overrides while active, register `hooks`, and limit automatic activation with `paths` globs. ## A practical checklist - Start from a real repetition: the third time you paste the same prompt. - Write the description for the model: what it does, and when to use it. - Put live facts in with `!` injection instead of asking Claude to run commands, and guard commands that may exit non-zero. - Mark side-effecting skills `disable-model-invocation: true` and pre-approve only the exact commands needed. - Field names must match exactly. Claude Code ignores unrecognized fields without an error, so a typo like `allowed_tools` silently does nothing. Malformed YAML loads the skill with no fields set. Test the skill after writing it. - Commit it to `.claude/skills/` and review changes like code. ## Conclusion Skills are the right home for procedures: loaded on demand, shareable through the repository, and controllable down to who may start them and which commands run without a prompt. Keep CLAUDE.md for the facts that always apply, and move every recurring checklist into a skill. [Atlas](https://bridge-terminal.com/atlas/) is a team of AI engineers built on Claude Code, where each engineer has a written role. Attaching your own skills to those roles is on Atlas's list to build in, so it works without any setup on your side; until then, keep your procedures as project skills in `.claude/skills/`, as described above. ## Questions people ask ### What is a skill in Claude Code? A skill is a directory containing a SKILL.md file with YAML frontmatter and Markdown instructions. Claude loads it when it is relevant, or you run it as /skill-name. Its body loads only when used. ### What is the difference between a skill and CLAUDE.md? CLAUDE.md holds facts that are always loaded. A skill's body loads only when it is used, so long procedures cost little context until needed. ### Do custom slash commands still work? Yes. Commands have been merged into skills, and a file in .claude/commands/ still creates the same command as the matching skill. If both share a name, the skill wins. Skills add supporting files and invocation controls. ### How do I stop Claude from running a skill on its own? Set disable-model-invocation: true in the frontmatter. You can still run it with /skill-name, but Claude cannot load it automatically. ### How do I pass a value to a skill? Use $ARGUMENTS for everything after the skill name, or $0, $1 and so on for individual values. Running /fix-issue 123 substitutes 123 into the text. ## About Atlas: Written roles for every engineer, not just one Skills give one Claude Code session a reusable procedure. Atlas is a team of AI engineers on Claude Code where each engineer is its own session with a written role, a deliverable and the evidence it must produce. Lessons from finished work are passed on to future engineers. — https://bridge-terminal.com/atlas/ ## Sources - [Extend Claude with skills (Claude Code docs)](https://code.claude.com/docs/en/skills) - [Custom commands and skills (Claude Code docs, slash-commands page)](https://code.claude.com/docs/en/slash-commands) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [Claude Code OpenTelemetry: Track Cost and Tool Use](https://bridge-terminal.com/atlas/blog/claude-code-opentelemetry-monitor-cost-usage/) - [Claude Code settings.json: Scopes and Precedence Explained](https://bridge-terminal.com/atlas/blog/claude-code-settings-json-scopes-precedence/) - [Claude Code Plugins: Build a Team Marketplace](https://bridge-terminal.com/atlas/blog/claude-code-plugins-team-marketplace-setup/) --- # How to Check AI-Built Software When You Don't Write Code > You can't read the code, but you can still tell whether an AI agent's work is good. Ask for evidence, set pass/fail checks, and try the edge cases yourself. Canonical: https://bridge-terminal.com/atlas/blog/check-ai-built-software-without-code/ Last updated: 2026-10-15 Published 15 October 2026 · Plain English · How-to · 6 min read ## The short version - You can judge AI-built software without reading code. Ask for evidence such as test results and screenshots instead of accepting a message that says the work is done. - Anthropic's guide for Claude Code says the agent stops when the work looks done, so write down beforehand what done means, as checks that clearly pass or fail. - Have the work checked by a reviewer that did not write it, and ask it to flag only problems that affect correctness or your stated requirements. - Try the awkward cases yourself: wrong inputs, empty fields, a logged-out user, a slow connection. Work that looks finished but isn't usually breaks there. - If nobody can show you that a change works, it is not ready to release, however confident the agent sounds. You can check AI-built software without reading a line of code. Instead of judging the code, judge the evidence: what was tested, what the result was, and what the screen looks like now. Settle what "done" means before the work starts and ask for proof afterwards. That is usually enough to tell good work from work that only looks finished. This guide is for founders, product owners, analysts, testers and managers who brief AI coding agents such as Claude Code or OpenAI Codex, or who oversee people who do. ## Why "it's done" is not enough An AI coding agent is a program that reads a project's files, makes changes and runs commands to finish a task you describe. It can work for long stretches on its own, and it has one habit you need to understand. Anthropic's best-practice guide for Claude Code says it directly: "Claude stops when the work looks done." Without a check the agent can run, the guide goes on, "looks done" is the only signal available, and "you become the verification loop: every mistake waits for you to notice it." The same guide lists a common failure it calls the trust-then-verify gap: the agent "produces a plausible-looking implementation that doesn't handle edge cases." An edge case is an unusual situation, such as an empty field or a very long name. The guide's advice is short: "If you can't verify it, don't ship it." So if you don't code, don't ask "is this code good?" Ask "what proof do I have that this does what I asked?" ## Step 1: Define "done" before the work starts The best checks are written before anything is built. In the brief, describe the result you will accept, not only the feature. A vague brief: "Add a discount code box to checkout." A brief you can check: - A valid code takes 10% off the total, and the new total shows before payment. - An expired code shows "This code has expired" and changes nothing. - A made-up code shows "Code not recognised". - Using the same code twice in one order is refused. - Before and after screenshots of the checkout page come with the work. Each line either happens or doesn't, and that is what makes it useful. Anthropic's guide recommends giving the agent "something that produces a pass or fail": example inputs with the answers you expect, for instance, or a screenshot to compare against a design. With a check like that, the agent can run it itself and keep going until it passes, instead of waiting for you to find the problem. For bigger features, the guide suggests letting the agent interview you first, asking about edge cases and trade-offs, and then write a spec (a written description of what will be built). The most useful specs, it says, state what is out of scope and "end with an end-to-end verification step that proves the feature works." You don't need technical knowledge for this. You only answer questions about how the business should behave. ## Step 2: Ask for evidence, not a summary When the agent reports back, a confident summary is not proof. Ask for the things that are. Anthropic's guide recommends having the agent "show evidence rather than asserting success: the test output, the command it ran and what it returned, or a screenshot of the result." It notes that reviewing evidence is faster than running the check again yourself, and "it works for sessions you weren't watching." What to ask for, in plain words: - **Test results.** A test is a small automatic check that runs the software and compares what happens with what should happen. Ask which tests were run, how many passed, whether any failed and whether any were skipped. - **Screenshots.** For anything on screen, ask for screenshots of the finished result. Include error messages and empty screens, not only the case where everything goes right. - **A list of what changed.** Ask which parts of the product were touched. If you asked for a discount box and the list includes the sign-in page, ask why. - **What was not done.** Ask directly: "What did you leave out, and what are you unsure about?" ### Warning signs in a report - "Should work now", with no test results. - Tests were switched off, skipped or deleted so that everything passes. - An error was hidden instead of fixed. One of the guide's example instructions tells the agent to "address the root cause, don't suppress the error." - Changes far outside what you asked for. ## Step 3: Get a second opinion from something that did not write the code People find it hard to review their own work, and agents do too. Anthropic's guide notes that in a fresh session (a new conversation that has not seen the earlier work) Claude "won't be biased toward code it just wrote." It suggests a reviewer that "sees only the diff and the criteria you give it." A diff is the list of exact changes. You don't have to run the review yourself. You only need to make sure one happens and read its verdict. The guide adds a caution: a reviewer told to find gaps "will usually report some, even when the work is sound." If you act on every comment, you end up with over-engineering: extra layers, defensive code and tests for cases that can't happen. Tell the reviewer to flag only problems that affect correctness or your stated requirements, and treat the rest as optional. ## Step 4: Try it yourself, the awkward way Testers already do this, and everyone else can too. Use the feature the way a careless, impatient or unlucky customer would: - Type the wrong thing: letters in a phone field, a date in the past, a very long name. - Leave fields empty and press submit. - Use it logged out, or as a user with fewer permissions. - Press the button twice quickly. - Try it on a phone and on a slow connection. - Go back, refresh, and check whether your data is still there. These are the edge cases where a "plausible-looking implementation" tends to fail. When you find a problem, report it the way the guide suggests for bugs: the symptom, where it likely happens, and what "fixed" looks like. "After the session times out, logging in fails; fixed means I can log in again without clearing my browser" is more useful than "login is broken." ## How do I judge quality beyond "does it work"? Working is the minimum. A few more questions, all answerable without code: - **Security.** Did anything touching sign-in, payments or personal data get its own security check? Ask what was checked, not only whether it was. - **Speed.** Is there a target ("search results in under a second"), and was it measured? - **Undoing a release.** If this release goes wrong, how do we go back, and has that been tried? Was the data backed up first? - **Consistency.** Does the new screen look and behave like the rest of the product? If nobody can answer one of these, you have found a gap. ## What your role becomes When AI agents do the building, a non-technical owner stops checking the work line by line. The job becomes setting the standard and checking the proof. In practice that means three things: 1. Write briefs with pass/fail acceptance criteria. 2. Don't accept "done" without evidence. 3. Keep the decisions that carry real risk, such as go-live, spending and deleting data, in human hands. Some tools build these habits into the process. [Atlas](https://bridge-terminal.com/atlas/) is a software team of AI engineers built on Claude Code. It won't let work be marked done until a screen has its test cases and screenshots. Each build is reviewed when it is finished and is either marked releasable or gets fix tasks sent back to the engineer who built it. Go-lives, spending and deleting data are never decided for you. Whatever tool you use, the habits above still apply. ## Summary You don't need to read code to hold AI-built software to a high standard. Decide what "done" means before the work starts. Ask for test results and screenshots instead of reassurance. Make sure something other than the author reviews the work. Then try the awkward cases yourself. If nobody can show you that a change works, it isn't ready, however good the summary sounds. ## Questions people ask ### How can I tell if code written by AI is any good if I can't code? Judge the evidence rather than the code: test results, screenshots of the finished screens, and a list of what changed. Set pass/fail acceptance criteria before the work starts, then compare the evidence with them. ### Why does an AI coding agent say a task is finished when it isn't? Anthropic's guide for Claude Code says the agent stops when the work looks done. If it has no check it can run, such as tests or a screenshot to compare against a design, looking done is the only signal it has. ### What should I ask an AI coding agent to show me before I approve a change? Ask which tests ran and whether any failed or were skipped. Ask for screenshots, including error messages and empty screens, a list of what changed, and what it left out or is unsure about. ### Should a different AI review the code the first one wrote? Yes. A reviewer in a fresh session is not biased toward code it just wrote. Ask it to flag only problems that affect correctness or your requirements, because a reviewer told to find gaps usually reports some even when the work is sound. ## About Atlas: Atlas asks for the proof before it calls work done In Atlas, a screen can't be marked done until it has its test cases and screenshots. Each build is reviewed when it is finished and is either marked releasable or gets fix tasks sent back to its builder by name. The Tests screen holds the case library, the test runs, the screenshots and a step-by-step replay, so you can check the evidence without reading code. — https://bridge-terminal.com/atlas/ ## Sources - [Best practices for Claude Code (Anthropic)](https://code.claude.com/docs/en/best-practices) - [Atlas: an AI engineering team built on Claude Code](https://bridge-terminal.com/atlas/) _Researched and drafted with Claude, then checked against the sources above. Atlas is an independent product, not affiliated with Anthropic or OpenAI._ ## Related - [AI Coding Agent Usage Limits Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-usage-limits-plain-english/) - [AI Coding Agent Terms Explained in Plain English](https://bridge-terminal.com/atlas/blog/ai-coding-agent-terms-plain-english-glossary/) - [Agent Skills Now Belong to a Foundation: What It Means](https://bridge-terminal.com/atlas/blog/agent-skills-open-standard-agentic-ai-foundation/) --- # Atlas Privacy > How the Atlas website and the Atlas app handle your information: what is collected, why, how long it is kept and who to contact. Canonical: https://bridge-terminal.com/atlas/privacy.html Last updated: 2026-10-26 ## Privacy Updated 15 October 2026 This page says what Atlas collects, why, and where it goes. Questions: [atlas@bridge-terminal.com](mailto:atlas@bridge-terminal.com). ### Your code and conversations stay with you Atlas works on your machine, or in your own company's cloud account. Your source code, your chat with the PA, your documents and your project's data are never sent to us. ### Your Atlas account You sign in to Atlas with your email address: a code and a link are sent to it through an email delivery service. Atlas's service then keeps your email, your name, whether Atlas is for you or for a company, and your organisation. For each Mac you use it keeps a machine code and the Atlas version, and — while a team runs, about once an hour — which projects are running, so that the plan you are on can be checked. People who sign in with your company's email domain join your organisation, and its admin can see who is in it and their Macs. A company server registers with the same service when it is set up, and checks in hourly with its Atlas version and which projects are awake. ### The daily usage report The Atlas app — every copy downloaded from this website — sends one report a day to Atlas, so we can see that each licence is used as agreed. It contains: a machine code, the licence holder and licence terms, the Atlas and operating-system versions, the computer's host and user name, and for each project its name, its folder path and usage measures (such as how many tasks ran and how long they took). It also contains each project's Atlas log since the last report, with credentials masked. The licence screen in Atlas says this happens. Logs beyond that are sent only when you choose to send them (Settings → Send logs). ### Claude Atlas's engineers are Claude Code sessions signed in to the Claude account of the person who set the project up. What they send to Anthropic is governed by that account's terms with Anthropic. Atlas stores the sign-in in its own credential store and never shows it to anyone. ### Payments Licences are paid through Lemon Squeezy, which sells them to you as the merchant of record: it takes the payment, charges local tax where it applies, and sends the invoices. Your card or PayPal details go to Lemon Squeezy and its payment processors, never to Atlas. Atlas receives what it needs to give you your licences: your email, your organisation, how many licences you bought and when they renew. Lemon Squeezy's own privacy policy covers what it keeps. ### Signing in with DigitalOcean When Atlas runs in your company's cloud, you can connect your DigitalOcean account by signing in with DigitalOcean. Atlas then holds an access token for that account, inside the Atlas installation in that same account, and uses it only to create and manage what Atlas needs there: its cluster, storage, backups and the databases you ask it for. We do not keep a copy. You can withdraw access at any time from your DigitalOcean account's settings. ### Credentials you give Atlas Passwords and tokens you give Atlas for your project are kept in its credential store on your machine or in your cloud account, given to a tool only when that tool needs them, and masked in every log and report. ### This website This website uses Google Analytics to count visits and see which pages are read. Google sets cookies in your browser for this and receives your browser's address and the pages you visit here. It receives nothing from the Atlas app itself. You can block it with your browser's privacy settings or Google's [opt-out add-on](https://tools.google.com/dlpage/gaoptout). ### Keeping and deleting Usage reports are kept while your licence is active and for one year after. To have them deleted, write to [atlas@bridge-terminal.com](mailto:atlas@bridge-terminal.com). ## Related - [Atlas Terms](https://bridge-terminal.com/atlas/terms.html) - [Atlas — an AI software team built on Claude Code](https://bridge-terminal.com/atlas/) --- # Atlas Terms > The terms for using the Atlas app and the bridge-terminal.com website: licences, your work and data, and what Atlas does and does not promise. Canonical: https://bridge-terminal.com/atlas/terms.html Last updated: 2026-10-26 ## Terms Updated 15 October 2026 These terms cover your use of Atlas ("Atlas", "we", "us"). Using Atlas means you accept them. ### Licence and plans Atlas is licensed, not sold. Signed in, your Atlas team may work on one project at a time on your Mac, free. Each project in development on your organisation's server needs a licence, and a licence also lets the team work on one more project at once on a Mac. A licence covers developing with Atlas, not the software you build: that is yours to run anywhere, for any number of users. Do not share your account, resell Atlas, or work around its checks. Current prices are on the [Pricing](https://bridge-terminal.com/atlas/pricing.html) page. ### The free trial Each organisation gets 30 days from sign-up with one project in development on its server included, once. A personal account is an organisation of one, and a cloud account carries one trial however many organisations use it. When the trial ends, projects on the server pause with their work saved; nothing is deleted, and buying a licence starts them again. ### Paying for licences Licences are billed monthly in advance, per project in development at the same time, through Lemon Squeezy as merchant of record; local tax is added where it applies. Your organisation's admin assigns licences to people or to the server, and a licence can move once a month. You can cancel at any time: your licences then last until the end of the month you paid for. Refunds are covered by our [refund policy](https://bridge-terminal.com/atlas/refunds.html). If a payment fails and is not put right within 7 days, the licences it paid for stop and the projects using them pause, with their work saved. We may change prices with 30 days' notice by email; a change applies from your next payment after that. ### Your accounts and your costs Atlas works through accounts you own: your Claude account, your git hosting, and, in the cloud version, your DigitalOcean account. You are responsible for following those services' terms and for what they charge. Atlas shows what it spends, and in the cloud version lets you set a budget, but the bills are yours. ### Your work The code and documents Atlas produces for your project belong to you. Review what it ships before you rely on it, as you would any engineer's work. ### Reports The Atlas app sends a daily usage report, described on the [Privacy](https://bridge-terminal.com/atlas/privacy.html) page. ### No warranty Atlas is provided as it is. To the extent the law allows, we are not liable for indirect losses, lost data or lost profits arising from its use, and our total liability is limited to what you paid for your licence in the twelve months before the claim. ### Changes We may update these terms. The date at the top says when they last changed. ## Related - [Atlas Privacy](https://bridge-terminal.com/atlas/privacy.html) - [Atlas Refund Policy](https://bridge-terminal.com/atlas/refunds.html) --- # Atlas Refund Policy > Atlas refund policy: cancel any time, licences last to the end of the paid month, and any payment is refunded in full if you ask within 14 days. Canonical: https://bridge-terminal.com/atlas/refunds.html Last updated: 2026-10-26 ## Refunds Updated 15 October 2026 Atlas licences are paid monthly, through Lemon Squeezy, our merchant of record. This page says how cancelling and refunds work. Questions: [atlas@bridge-terminal.com](mailto:atlas@bridge-terminal.com). ### Cancel any time You can cancel your licences whenever you like. They keep working until the end of the month you have paid for, and you are not charged again. ### A full refund within 14 days If you ask within 14 days of a payment, we refund that payment in full — no questions about why. Write to [atlas@bridge-terminal.com](mailto:atlas@bridge-terminal.com) from the email you sign in to Atlas with, and say which payment. The licences it paid for stop when the refund is made. ### How the money comes back Refunds go back the way you paid — to the same card or PayPal account — through Lemon Squeezy, which also adjusts any tax that was charged. Your bank may take a few days to show it. ### The free plan and the trial One project on your Mac is free, and every team's first 30 days include a server project free, so there is nothing to refund for those. When the trial ends, projects on your server pause with their work saved; nothing is deleted. ## Related - [Atlas Pricing — Free on Your Mac, $50 per Project in Development](https://bridge-terminal.com/atlas/pricing.html) - [Atlas Terms](https://bridge-terminal.com/atlas/terms.html)