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.

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:

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:

---
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:

---
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):

---
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: <value> 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:

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:

---
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 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:

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:

---
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. 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 is a team of AI engineers built on Claude Code, where each engineer has a written role. Whether Atlas lets you attach your own skills to those roles is covered below.

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 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.

Claude Haiku 5.5 is Anthropic's new small model, released on 7 October 2026. It is the fastest and cheapest model in Anthropic's current line-up. It costs $0.10 for every million tokens it reads and $0.50 for every million it writes, as long as the prompt stays under 100,000 tokens (a token is a small piece of a word). It can read about 555,000 words at once. It will not replace the bigger models for hard building work, but it makes a lot of routine work much cheaper.

This article covers what Claude Haiku 5.5 is, what changed since the last Haiku, and what it means for a team that builds software with AI coding agents.

What is Claude Haiku 5.5?

Anthropic's models overview lists four current models: Fable 5.1, Opus 5.5, Sonnet 5.5 and Haiku 5.5. Haiku 5.5 is listed as the fastest of the four and has the lowest price. Anthropic describes it as the model "for high-volume, latency-sensitive tasks such as classification, extraction, and routing". In plain words, it is for jobs you run thousands of times where a quick answer matters: sorting incoming tickets, pulling fields out of documents, or deciding which specialist a request should go to.

Anthropic's Haiku 5.5 page adds a fourth use that matters to coding teams: "subagent tasks". A subagent is a helper that a main AI agent sends off to do one narrow job, such as searching the code or summarising a log, before it reports back.

From launch, the model was available through Anthropic's own API (the service developers call from their code) and on Amazon Bedrock, Google Cloud, Microsoft Foundry and Claude Platform on AWS. Anthropic says it will not retire the model before 7 October 2027.

Does Claude Code use Haiku 5.5?

Yes. The release notes for Claude Code version 2.1.293, published on 7 October, say Haiku 5.5 is "now the default Haiku model on the Anthropic API". So if you use Claude Code through Anthropic's API, the work it hands to its Haiku model now goes to 5.5 once you are on that version or later.

What changed from Haiku 4.5?

Anthropic's what's new page lists the main differences:

• Much more room to read. The context window (how much text the model can hold in mind at once) grows from 200,000 tokens to 1 million.
• Longer answers. One reply can be up to 128,000 tokens long, up from 64,000.
• It decides how much to think. Haiku 5.5 now chooses for itself how much to reason before it answers. A setting called "effort" lets developers turn that up or down, trading quality against speed and cost. The default is medium.
• The same text counts as more tokens. Haiku 5.5 splits text into tokens in a newer way, so the same text comes out about 30% more tokens than on Haiku 4.5. You pay per token, so compare total bills, not only the price per token.
• More tokens in long conversations. In a back-and-forth conversation, the model's reasoning from all earlier turns now stays in its memory and is charged as input. Haiku 4.5 kept only the latest turn's reasoning.
• Cheaper repeated instructions. Prompt caching lets you pay much less when the same opening text is sent again. It now works on prompts as short as 512 tokens, down from 4,096.

Some changes also break existing code. Haiku 5.5 returns errors for some settings that older programs send, such as the ones that controlled how random the answers were, and for the older way of setting a fixed thinking budget. It also no longer accepts a common way of steering a reply, which was writing the first words of the answer for the model. If your product already calls Haiku 4.5, moving to 5.5 takes some developer work. Changing the model name is not enough.

How much does Haiku 5.5 cost?

Prices from Anthropic's Haiku 5.5 page, in US dollars per million tokens:

• Prompts up to 100,000 tokens: $0.10 to read, $0.50 to write.
• Prompts over 100,000 tokens: $0.50 to read, $2.50 to write, five times as much.
• Re-reading cached text: $0.01 (or $0.05 for prompts over 100,000 tokens).
• Batch jobs (work you can wait for instead of getting it back at once): 50% off.

For comparison, the models overview lists Sonnet 5.5 at $2 to read and $10 to write, and Opus 5.5 at $4 and $20. For short prompts, Haiku 5.5 reads text at a twentieth of Sonnet's price and a fortieth of Opus's.

The catch is the 100,000-token line. The 1-million-token window is useful, but once a prompt goes over that line, every token in that request costs five times the base rate, including the reply. Cached text counts toward the line too. A job that loads a whole codebase into every request will cost much more than the headline price suggests. Anthropic's cost guide suggests shortening a long session when one task ends, before its requests pass 100,000 tokens.

Is Haiku 5.5 good enough for coding?

That depends on the job. Anthropic's guide to choosing a model says "most workloads start with Claude Opus 5.5". It points to Opus for "multihour autonomous coding agents" and to Sonnet 5.5 for everyday coding. Haiku 5.5 is listed for "the lowest latency and price", including "sub-agent tasks". The same guide also describes a cheaper starting route: begin with Haiku 5.5, test it, and move up only where it falls short. It suggests that route for prototypes, cost-sensitive products and high-volume, straightforward tasks.

The cost guide gives one direct comparison. On GPQA Diamond, a hard science-reasoning test, Haiku 5.5 scored 85% at its default setting, against 91% for both Opus 5.5 and Sonnet 5.5. (Anthropic notes that Opus and Sonnet tied only because refusals counted as wrong answers.) Haiku's cost per correct answer was "about a twentieth of Claude Opus 5.5's cost per correct answer and about a tenth of Claude Sonnet 5.5's". The guide says Haiku 5.5 "suits high-volume and latency-sensitive work with checkable outputs". It calls its figures internal and "directional, not guarantees", and tells readers to measure on their own work.

"Checkable" is the important word. If a wrong answer gets caught because a test fails, a format check rejects it or a reviewer spots it, a cheaper model that is usually right can save a lot. If wrong answers slip through unnoticed, the savings can turn into rework.

What does this mean for a team building software?

One option is to mix models. Anthropic's cost guide describes two ways to do that:

1. A big model in charge, smaller models doing the bulk work. The capable model plans and checks, and cheaper models handle many separate pieces. In Anthropic's measurements, which used an earlier Sonnet model as the helpers rather than Haiku 5.5, this saved money in only two cases: routine work where a few pieces cost far more than the rest, and work too big for one model to read at once. Otherwise, the main model on its own at a lower effort setting came out ahead.
2. A small model doing the work and asking a big model for advice. The cheaper model runs the task and asks a stronger "advisor" model only at hard moments. This helps only if the small model actually asks. In one of Anthropic's tests, Haiku 5.5 paired with an Opus 5.5 advisor never asked once across 198 questions. The pair scored about the same as Haiku alone and cost 12% more per question.

Before trying either approach, Anthropic suggests a simpler step: turn down the effort setting on the model you already use. Its model guide says "tuning effort is often a better lever than switching models".

For a founder or manager, these are the questions to ask your team:

• Which of our AI tasks are high-volume and easy to check? Likely candidates are ticket triage, summarising test logs, tagging data and first-pass searches through code. Architecture design and fixing subtle bugs are not.
• Have we tested it on our own work? Anthropic suggests taking a few real tasks from your own logs, writing a check for each that shows whether it succeeded, and recording the cost of each task next to its score. Run the same set on your current model and on Haiku 5.5, and compare cost per finished task as well as price per token.
• Are we filling the big window? If prompts often go over 100,000 tokens, the higher rate applies. Cutting down what goes into each request may save more than changing models.
• Who updates the code? If your product calls Haiku 4.5 today, set aside some developer time for the breaking changes.
• Will we check again? Anthropic says to "recheck at every model release", because each new model changes both the quality gap and the price gap.

How Atlas relates to this

Atlas runs each AI engineer as its own Claude Code session, with the model and effort chosen to suit that engineer's role. That follows the same idea: not every job needs the biggest model. Atlas's published material does not say that any role uses Haiku 5.5, or that Atlas tests a new model against a role's past results before switching. In Atlas or anywhere else, treat a model change as something to measure first.

The bottom line

Claude Haiku 5.5 makes fast, simple, repeated AI work much cheaper, and it can read far more at once than the last Haiku. It does not replace Opus or Sonnet for the hard parts of building software, and long prompts cost five times as much. Anthropic's advice is to find the high-volume jobs where mistakes get caught, test Haiku 5.5 on those jobs with your own work before moving anything over, and check again when the next model comes out.

MCP servers give an AI coding agent access to things outside your repository, such as a database, an issue tracker or an internal API. In Claude Code you add one with claude mcp add and choose whether it is private to you or shared with the team through a .mcp.json file. Claude can then call that server's tools the same way it calls its built-in ones. This guide covers how that works, the commands you need, and the settings that matter once you have more than one or two servers.

What an MCP server actually is

The Model Context Protocol (MCP) is described by its maintainers as "an open-source standard for connecting AI applications to external systems." An application that supports MCP can connect to data sources (local files, databases), tools (search engines, calculators) and workflows (specialized prompts).

A server can expose three kinds of things to Claude Code:

• Tools: functions Claude can call, such as "run this query" or "create an issue". In Claude Code their full names look like mcp__<server>__<tool>.
• Resources: data you pull into a prompt with an @ mention, for example @github:issue://123 or @postgres:schema://users.
• Prompts: workflows that appear as commands. Claude Code lists them as /servername:promptname (MCP), and you can also type the long form, for example /mcp__github__pr_review 456.

Because the protocol is open, one server can work with many clients. The MCP project lists Claude, ChatGPT, Visual Studio Code and Cursor among the clients that support it. Each client has its own configuration format, so the commands below apply only to Claude Code.

Remote and local servers

Remote HTTP servers run elsewhere and you reach them by URL. Claude Code's documentation recommends HTTP for remote servers:

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server takes a static token, pass it as a header:

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

The older SSE transport is deprecated. Claude Code tries HTTP first and switches to SSE when a server does not accept it; that automatic switch needs v2.1.265 or later. On older versions, pass --transport sse for SSE-only servers.

Local stdio servers are programs Claude Code starts on your machine. The -- separates Claude Code's own options (--transport, --env, --scope) from the command that runs the server, and everything after it is passed to the server untouched:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

Claude Code sets CLAUDE_PROJECT_DIR in a stdio server's environment to the project root, so a local server can tell which project it is working in.

For browsers, Claude Code also has a built-in Claude in Chrome server, which admin controls treat separately (see the security section below).

Scopes: who gets the server

Every server has a scope, set with --scope. It decides who sees the server and where it is stored:

# Shared with everyone who clones the repo
claude mcp add --transport http shared-server --scope project https://example.com/mcp

# Available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

If the same name is defined in more than one place, precedence is local, then project, then user, then plugin-provided servers, then claude.ai connectors. A server an organization provides through the managedMcpServers managed setting ranks above all of these. The winning entry is used whole; fields are not merged across scopes.

A sensible split: project for servers the whole team needs on this codebase, user for personal tools you want everywhere, and local for experiments or anything holding your own credentials.

The .mcp.json file and keeping secrets out of git

A project-scoped server is written to .mcp.json, which you commit:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

Do not commit real tokens here. Use environment variable expansion: ${VAR} reads a variable, and ${VAR:-default} falls back to a default when it is unset. Expansion works in command, args, env, url and headers:

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Two details catch people out:

• An unset variable with no default is left as the literal ${VAR} text. The config still loads, and Claude Code reports a missing-variable warning.
• In a remote server's url and headers, certain credential variables always read as empty, and a :-default on them is ignored. Examples include ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, AWS_BEARER_TOKEN_BEDROCK, HTTPS_PROXY and NPM_TOKEN. If a server needs one of those values, copy it into a variable with your own name.

For short-lived tokens or SSO, headersHelper runs a command that prints a JSON object of headers. It runs fresh on each connection, is not cached, and is abandoned after 10 seconds. If a tool call returns 401 or 403, Claude Code re-runs the helper and retries the call once.

Authentication with OAuth

Many hosted servers use OAuth instead of static tokens. Add the server, then sign in:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Inside Claude Code, run /mcp and complete the browser login. From the shell:

claude mcp login sentry
claude mcp login sentry --no-browser   # print the URL instead of opening a browser

claude mcp login prints the URL on its own when no local browser is available, which helps over SSH. claude mcp logout <name> clears stored credentials. If a server needs a pre-registered redirect URI, fix the port with --callback-port. claude -p and Agent SDK runs cannot run the OAuth flow, so sign in from an interactive session first. Removing a remote server also deletes the OAuth tokens and client registration stored for it.

Managing and debugging servers

claude mcp list              # all servers and their status
claude mcp get notion        # details for one server
claude mcp remove notion     # remove it

claude mcp list shows states such as ✔ Connected, ! Needs authentication, ✘ Failed to connect and ⏸ Pending approval. Inside a session, /mcp lets you sign in, turn a server off without losing its configuration, and reconnect it; /mcp reconnect all retries every failed server.

If a slow server will not start, raise the startup timeout (in milliseconds):

MCP_TIMEOUT=10000 claude

A "timeout" field in a server's .mcp.json entry sets that server's tool timeout in milliseconds and overrides MCP_TOOL_TIMEOUT for it.

If you already set servers up in Claude Desktop, claude mcp add-from-claude-desktop imports them on macOS and WSL. In the other direction, claude mcp serve runs Claude Code itself as a stdio MCP server for other clients.

Context, output limits and tool search

Every tool definition costs context. Claude Code handles this with tool search, on by default on supported models: only tool names and server instructions load at session start, and full definitions load when Claude needs them. You can tune it with ENABLE_TOOL_SEARCH:

ENABLE_TOOL_SEARCH=auto:5 claude   # load upfront while definitions total under 5% of context
ENABLE_TOOL_SEARCH=false claude    # load everything upfront

Claude Code turns tool search off when ANTHROPIC_BASE_URL points to a non-first-party host, because most proxies do not forward the blocks it needs; setting ENABLE_TOOL_SEARCH explicitly overrides that.

To keep a server's tools always visible, set "alwaysLoad": true on it. Each upfront tool uses context, and startup waits for that server's tools (up to the 5-second connect timeout), so reserve this for the few tools Claude needs on every turn.

Tool output is capped as well. Claude Code warns when a tool returns more than 10,000 tokens, and the default maximum is 25,000 tokens. You can raise it:

MAX_MCP_OUTPUT_TOKENS=50000 claude

Separately, a successful text result longer than 50,000 characters is saved to a file and replaced with a file reference, whatever MAX_MCP_OUTPUT_TOKENS is set to. Database servers hit these limits most, because a full schema or large query result easily goes over. A server author can raise the threshold for one tool, such as get_schema, with the anthropic/maxResultSizeChars annotation, up to 500,000 characters.

Security: approval, prompt injection and team controls

The documentation says to verify you trust each server before connecting it, and warns that servers fetching external content can expose you to prompt injection. A server can read data and act on your behalf, so review it as you would a new dependency.

Built-in safeguards:

• Project servers need approval. In interactive sessions, Claude Code asks before using servers from a cloned .mcp.json. Reset those choices with claude mcp reset-project-choices.
• Headless runs do not ask. In claude -p, Agent SDK and cloud sessions, project servers load without a prompt. To block one, add it to disabledMcpjsonServers in settings. This matters if you run Claude Code in CI.
• Per-tool approval. A server author can mark a tool with anthropic/requiresUserInteraction so it prompts on every call, even in acceptEdits, auto and bypassPermissions modes. In dontAsk mode the call is denied.

For organizations, administrators can control MCP centrally:

• A managed-mcp.json file at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows) takes exclusive control. Users cannot add or use other servers, including plugin servers. An empty mcpServers map blocks every server except the few that still load under exclusive control.
• allowedMcpServers and deniedMcpServers in managed settings filter what users configure. Match on serverUrl or serverCommand. The docs say a serverName entry "is not a security control", because a user can call any server github.
• With managed-mcp.json deployed, Claude in Chrome is blocked in terminal sessions unless allowClaudeInChromeWithManagedMcp is set in the device's own managed settings.

Where to start

Add one remote server over HTTP, sign in with /mcp, and check claude mcp list before adding more. Put team-wide servers in .mcp.json with ${VAR} placeholders, and keep personal credentials in local or user scope. Leave tool search on, and raise output limits only for servers that need it, which usually means databases. Before anything runs unattended, decide which project servers a headless run may load. A CLAUDE.md file is a good place to tell the agent when to use each server.

For more on running several Claude Code sessions as a team, see the Atlas home page.

To cut Claude Code costs, keep the context small and use the cheapest model and effort level that can do the job. Every request re-sends the whole conversation. Anthropic's docs say that unexpectedly high spend on an API or cloud-provider plan usually comes from long sessions that were never cleared or from Opus left as the default model. Below: how to see where your usage goes, which habits matter most, and which controls a team lead has on each type of plan.

The details come from Anthropic's Claude Code documentation on costs and prompt caching. Commands and plan details change between versions, so run claude --version and check the docs if something on your screen doesn't match.

How Claude Code costs and usage limits work

Claude Code is billed by API token consumption. What that means for you depends on how you sign in:

• Pro and Max (individual subscriptions): usage is included in the plan, up to its limits. Past a limit, you can turn on usage credits to keep working.
• Team and Enterprise: each member's Claude Code usage comes out of a per-seat allowance that resets on a rolling five-hour window and a weekly window. The allowance is shared with Claude chat and Cowork, and its size depends on the seat tier (Standard or Premium).
• Claude Console (API key): billed per token to your organization, with workspace spend limits.
• Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry: billed per token to your cloud account. Spend controls are your cloud provider's budget tools.

For scale, Anthropic reports an average across enterprise deployments of about $13 per developer per active day and $150–250 per developer per month, with 90% of users staying under $30 per active day. Your numbers will depend on model choice, codebase size, and how much you run in parallel or in automation. Anthropic recommends a small pilot group to establish a baseline before a wider rollout.

Measure first: /usage, /context and /insights

/usage opens with a Session block showing token counts by model (input, output, cache read, cache write) and a dollar figure. Claude Code calculates that figure locally at list price, so treat it as an estimate; authoritative billing is on the Usage page in the Claude Console. Since v2.1.211 the Session totals reset when you run /clear. From v2.1.251 there is also a Prompt cache (main) line with the share of input served from cache, the number of misses, and whether the cache is warm right now. It covers the main conversation only, not subagents.

On a subscription, the session dollar figure doesn't affect your bill. On Pro, Max, Team and Enterprise plans, what matters is the plan usage bars and the breakdown below them:

• Attribution: the share of recent usage from skills, subagents, plugins and individual MCP servers.
• Behavior flags: patterns such as long context or cache misses, flagged when one accounts for 10% or more of recent usage, each with a tip for reducing it.
• Loops: the heaviest /loop and other scheduled tasks, with total and per-run tokens (v2.1.242 or later).

Press d or w to switch between the last 24 hours and the last 7 days. The breakdown is approximate and built from session history on your machine, so it leaves out usage from other devices and from claude.ai.

/context shows what is taking up the context window right now. Use it when sessions feel expensive and you don't know why.

/insights writes an HTML report on how you work: what you work on, friction points such as misunderstood requests or buggy code, and suggestions. The latest report is saved to ~/.claude/usage-data/report.html. The analysis itself counts against your plan or API usage.

The habits that save the most

The docs name two habits as the highest-impact: clearing between unrelated tasks and matching the model to the job.

Use /clear between unrelated tasks

Claude Code sends the full conversation with every request, plus another request each time Claude uses tools. Prompt caching bills re-reads at the lower cached-token rate, but a one-line question in a session that has been open all day still draws usage for the whole conversation.

When you move to unrelated work, start fresh:

/rename auth-refactor
/clear

/rename lets you find the old session later with /resume. /clear costs nothing. /compact sends a request containing the whole conversation to produce a summary. While the cache is warm, most of that is read from cache, but after a break longer than the cache lifetime it reprocesses the full history as uncached input. Compact at a natural break when you need continuity; clear when you don't. If you went down a path you want to abandon, /rewind to an earlier turn instead: it goes back to a prefix that is already cached.

If you do compact, tell it what to keep:

/compact Focus on code samples and API usage

You can also put standing compaction instructions in CLAUDE.md:

# Compact instructions

When you are using compact, please focus on test output and code changes

Match the model to the task

The docs say Sonnet handles most coding tasks well and costs less than Opus, and recommend reserving Opus for complex architectural decisions or multi-step reasoning. Switch mid-session with /model, or set a default in /config.

Three things are easy to miss:

• Switching to Opus also switches the subagents that inherit your session's model.
• For simple subagent tasks, set model: haiku in the subagent's configuration. For more on when subagents are worth it, see Claude Code Subagents: When to Split Work and How.
• Each model has its own prompt cache, so a mid-session model switch makes the next request reprocess the whole conversation. Pick the model at the start of a session where you can.

Lower effort for simple work

Extended thinking is on by default, and thinking tokens are billed as output tokens. Depending on the model, the default budget can be tens of thousands of tokens per request. For routine work, lower the effort level with /effort or in /model, or disable thinking in /config. Opus 5.5, Sonnet 5.5, Haiku 5.5 and the Fable models always use extended thinking and can't have it turned off, so effort is the setting to adjust there.

Changing effort mid-session also has a cache cost on most models: the next request reprocesses the conversation. The exception is Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 used with an API key or a Claude subscription, where the cache is kept (not on Bedrock, Google Cloud's Agent Platform or a Claude apps gateway).

On models with a fixed thinking budget, you can also lower it with an environment variable:

MAX_THINKING_TOKENS=8000

Adaptive-reasoning models ignore nonzero budgets, so use effort levels with those instead.

Write specific prompts and plan before building

A vague prompt like "improve this codebase" triggers broad scanning. "Add input validation to the login function in auth.ts" lets Claude read only what it needs. For bigger changes:

• Press Shift+Tab to cycle to plan mode, so Claude proposes an approach for your approval before writing code. Re-work after a wrong first direction is expensive.
• Press Escape as soon as Claude heads the wrong way. Use /rewind or double-tap Escape to restore an earlier checkpoint.
• Give it verification targets such as test cases or expected output, so Claude catches its own mistakes before you have to ask for fixes.

Shrink the context Claude starts with

Anything loaded at session start is carried in every request of that session.

• Keep CLAUDE.md short. The docs suggest staying under 200 lines and moving workflow-specific instructions, such as PR reviews or database migrations, into skills, which load only when invoked. Our CLAUDE.md best practices covers what belongs in the file.
• Trim MCP servers. MCP tool definitions are deferred by default, so only tool names and server instructions enter context until a tool is used. Still, run /mcp and disable servers you aren't using. Where a CLI exists (gh, aws, gcloud, sentry-cli), it is more context-efficient than an MCP server because it adds no per-tool listing.
• Install code intelligence plugins for typed languages. One "go to definition" call can replace a grep followed by reading several candidate files.

Filter noisy output before Claude reads it

Test runners and logs fill context fast. A PreToolUse hook can rewrite a command so Claude sees only what matters. This is the example from the docs, which pipes test output through a filter for failures. Add it to settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

Create the folder with mkdir -p ~/.claude/hooks, save the script as ~/.claude/hooks/filter-test-output.sh, and make it executable with chmod +x:

#!/bin/bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command')

# If running tests, filter to show only failures
if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "$input" | jq --arg filtered "$filtered_cmd" \
    '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "allow", updatedInput: (.tool_input + {command: $filtered})}}'
else
  echo "{}"
fi

Run /hooks and check that it appears under PreToolUse. Another option is to delegate verbose jobs such as test runs, documentation fetches and log processing to a subagent, so only a summary returns to your main conversation. The subagent's own requests still count against your usage, so give it a smaller model.

Why usage climbs in a long session

If your limits drain faster than your activity seems to justify, check these:

• Cache misses after breaks. On a subscription, within plan usage, the main conversation's prompt cache lasts an hour. It drops to five minutes once you're drawing on usage credits, and five minutes is the default on API keys and cloud providers. The promptCacheTtl setting (v2.1.242 or later) lets you choose 1h yourself; one-hour cache writes are billed at a higher rate. Your first message after a longer break reprocesses the full context. On Pro and Max, Claude Code offers to resume a large session from a summary after a long break.
• Scheduled tasks and loops fire on their interval while the session is idle, and each run sends your full context.
• Subagents send their own requests on top of the main conversation's, and get a five-minute cache by default even on a subscription. The attribution breakdown in /usage shows their share.
• Agent teams. Each teammate has its own context window, and the docs estimate about 7x the tokens of a standard session when teammates run in plan mode. Teams are off by default. If you enable them, keep teams small, use Sonnet for teammates, and shut teammates down when they finish.
• Background requests, such as summarizing past conversations for claude --resume, are small: typically under $0.04 per session.

Hitting a limit: what each message means

• "You've hit your session limit" / "weekly limit": a subscription usage window shared across all models, so switching models won't help. Wait for the reset time shown, or run /usage-credits if usage credits are turned on.
• "You've hit your Opus limit" / "Sonnet limit": model-specific. Switching to a model outside that family with /model lets you keep working.
• Spend limit messages (individual, org monthly, or team shared budget): usage credits have reached a cap an admin set. An admin raises it under Organization settings > Usage.
• Auto-compact warnings aren't usage limits. They mean the conversation is close to its auto-compact window.

Controls for team leads

• Team and Enterprise: the org analytics spend report shows estimated spend per user and per model, with CSV export. It covers usage-credit spend and appears once usage credits are on; usage inside the seat allowance isn't metered in dollars. With usage credits on, spend limits can be set per organization, group or member.
• Console: set workspace spend limits. A "Claude Code" workspace is created automatically the first time someone authenticates with a Console account. For organizations with custom rate limits, a workspace rate limit on it caps Claude Code's share so it can't crowd out other production workloads.
• Cloud providers: Anthropic's analytics don't cover this usage. For per-user attribution, use OpenTelemetry export, a self-hosted Claude apps gateway, or an LLM gateway.
• Contracted rates: the modelPricing managed setting (v2.1.242 or later) makes the figures in /usage, the status line and OpenTelemetry reflect your contracted prices instead of list price. It changes what Claude Code reports, not what you are charged.

If you run several agents in parallel, budget for each one, because every session has its own context. On Atlas, where each engineer is its own Claude Code session with model and effort tuned to its role, an optional daily budget warns at 50% and 80% and pauses the team at 100%.

Summary

Most Claude Code spend comes from context you no longer need and from models or effort levels set higher than the task requires. Clear between tasks, default to Sonnet, lower effort for routine work, keep CLAUDE.md and MCP lean, and filter noisy output before Claude reads it. Then check the /usage breakdown over the last 7 days to see which changes made a difference.

Claude Code's review looks for correctness bugs in a diff: logic errors, broken edge cases, security vulnerabilities and regressions, read against the rest of your codebase. By default, the managed reviewer doesn't flag formatting preferences or missing test coverage. It never approves or blocks a pull request, and it doesn't know whether the change was the right thing to build. Use it as a second reviewer that runs before a person looks, and tune it with a REVIEW.md file so it flags what your team cares about.

This guide covers the four ways to run it, what each one is for, and the settings that decide whether you get useful findings or noise.

Four ways to run AI code review in Claude Code

Local review with /code-review

/code-review

It reviews your branch's commits ahead of its upstream plus any uncommitted changes. You can also pass a target: a file path, a PR number, a branch name, or a ref range such as main...my-feature. It runs as a background subagent with its own context window, so it doesn't fill your conversation, and the findings arrive there when it finishes. /review is an alias for it.

Flags:

• --fix applies the findings to your working tree after the review.
• --comment posts findings as inline comments on a GitHub pull request, or as a single note on a GitLab merge request.
• --max-findings <n> (or all, or default) replaces the usual limit on how many findings it reports. It needs Claude Code v2.1.288 or later.

You can also pass an effort level. At low it reports only the findings it's most confident in, so you see fewer false positives; from medium through max it covers more ground. If you don't give a level, it reuses the last one you typed. One catch: /rewind doesn't undo the edits a background review makes with --fix, so revert them with git.

Deeper review with ultrareview

/code-review ultra
/code-review ultra 1234
/code-review ultra develop

These review your current branch against the default branch, then pull request #1234 on github.com, then your branch against develop. Ultrareview is a research preview. It runs a larger group of reviewer agents in a cloud sandbox, and every finding it reports is independently reproduced and verified. A review typically takes 15 to 25 minutes.

Pro and Max accounts get three free runs, a one-time allotment that doesn't refresh. After that a review typically costs $5 to $25 in usage credits, depending on the size of the change, and the launch dialog shows an estimate first. A branch review can include up to 500 changed files and 8,000 changed lines by default. Those limits can change, and the refusal message names the ones in effect.

For scripts and CI, use the subcommand. It waits for the review to finish (up to 45 minutes by default) and prints the findings to stdout; --json prints the raw findings payload:

claude ultrareview 1234 --json

Don't use claude -p '/code-review ultra' for this: it launches the cloud review and exits without the findings. Ultrareview needs a claude.ai sign-in and isn't available on Amazon Bedrock, Google Cloud's Agent Platform or Microsoft Foundry, or to organizations with Zero Data Retention or the HIPAA configuration. Where it isn't available, /code-review ultra runs a local review instead.

Managed Code Review on every pull request

Code Review is a research preview for Team and Enterprise plans, with the same Zero Data Retention and HIPAA exclusions. An Owner opens claude.ai/admin-settings/claude-code, installs the Claude GitHub App, selects repositories and picks a trigger for each:

• Once after PR creation: one review when the PR is opened or marked ready for review.
• After every push: a review on each push. It catches new issues as the PR changes and auto-resolves threads when you fix flagged issues, but it runs the most reviews and costs the most.
• Manual: reviews run only when someone comments @claude review (a single review) or @claude review always (a review, plus reviews on later pushes).

Several agents analyze the diff and surrounding code in parallel, each looking for a different class of issue. A verification step then checks candidates against how the code actually behaves, to filter out false positives. Findings arrive as inline comments tagged Important (fix before merging), Nit (minor, not blocking) or Pre-existing (a real bug this PR didn't introduce). Anthropic's docs put the average at $15–25 per review, scaling with PR size and complexity, and about 20 minutes per review. Code Review is billed through usage credits, not your plan's included usage.

Your own workflow with claude-code-action

To run review on your own runners and control the prompt, use the GitHub Action. The quickest route is /install-github-app inside Claude Code, selecting the review workflow. The manual version runs the code-review plugin when a PR is opened, updated, reopened or marked ready for review:

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"'

Keep both --comment and the claude_args line. Without --comment, Claude posts nothing and the findings appear only in the workflow log. The action starts the inline-comment tool only when --allowedTools in claude_args names it. To use a Claude subscription instead of an API key, use claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}. For more on running Claude non-interactively, see our guide to Claude Code headless mode in CI.

What AI code review catches

By default, managed Code Review focuses on correctness: "bugs that would break production, not formatting preferences or missing test coverage." That covers:

• Logic errors and broken edge cases. The docs' examples: a token refresh that races with logout and leaves stale sessions active, and a parser that silently returns 0 on malformed input.
• Security vulnerabilities.
• Subtle regressions, found by reading the change in the context of the full codebase, not only the diff.
• Pre-existing bugs that the PR didn't introduce, tagged separately.
• Rule violations and stale docs. Code Review reads your CLAUDE.md files, flags newly introduced violations as nits, and flags changes that make a CLAUDE.md statement outdated.

What it misses, or leaves to you

• It doesn't gate merges. The check run always ends with a neutral conclusion, so branch protection never blocks on it.
• It doesn't hold a conversation. Replying to an inline finding gets no response. Fix the code and push, or resolve the thread to dismiss it.
• Some PRs are skipped. Managed Code Review never reviews fork PRs automatically; someone with write access to the base repository must comment @claude review. The Action workflow skips draft and closed PRs, PRs that already have a comment from Claude, and PRs it judges don't need review, such as automated or trivial ones. On public repositories, GitHub withholds secrets from fork-triggered runs, so the Action reviews only PRs from branches in the same repository.
• Runs can fail. Reviews are best-effort. Code Review retries some interrupted reviews itself; otherwise the check run title says the review failed or timed out, and you rerun it with @claude review or, for non-fork PRs, the Re-run button.
• Big diffs hit limits. Ultrareview refuses diffs over its size limits, so split large changes.
• It can't judge intent. It checks the code for bugs, not whether the feature matches what was asked for or whether the change should exist at all.

Tune what it flags with REVIEW.md

For managed Code Review, the main lever is a REVIEW.md at the repository root. Its contents go directly to the agents that find and verify findings, so rules there land more reliably than the same rules in a long CLAUDE.md. Local /code-review follows CLAUDE.md but doesn't read REVIEW.md.

The docs list these as the patterns with the most impact:

• Redefine Important for your repo. A docs, config or prototype repo might want a much narrower definition.
• Cap nits, for example "report at most five nits, mention the rest as a count in the summary."
• Skip what you don't need reviewed: generated code, lockfiles, vendored dependencies, and anything CI already enforces.
• Add repo-specific checks, such as "new API routes must have an integration test."
• Set a verification bar, for example "behavior claims need a file:line citation in the source, not an inference from naming."
• Converge on re-review: "after the first review, suppress new nits and post Important findings only."

A short example, adapted from the docs:

# Review instructions

## What Important means here
Incorrect logic, unscoped database queries, PII in logs, and
migrations that aren't backward compatible. Style is Nit at most.

## Do not report
- Lint, formatting and type errors (CI enforces these)
- Files under `src/gen/` and any `*.lock` file

## Always check
- Database queries are scoped to the caller's tenant

Keep it short: the docs warn that a long REVIEW.md dilutes the rules that matter most. General project context belongs in CLAUDE.md; see our CLAUDE.md best practices.

Gate merges on findings yourself

To fail CI on Important findings, read the check run's output. Its Details text ends with a machine-readable comment. Find the check run ID first:

gh api repos/OWNER/REPO/commits/COMMIT_SHA/check-runs --jq '.check_runs[] | {id, name}'

Take the id of the Claude Code Review run, then parse the severity counts:

gh api repos/OWNER/REPO/check-runs/CHECK_RUN_ID \
  --jq '.output.text | split("bughunter-severity: ")[1] | split(" -->")[0] | fromjson'

This returns counts such as {"normal": 2, "nit": 1, "pre_existing": 0}, where normal is the number of Important findings. Fail the job when it's above zero, and keep a way for a person to override it.

Keep costs predictable

• Choose the trigger deliberately. "After every push" multiplies cost by the number of pushes; "Once after PR creation" runs one review per PR; "Manual" costs only what someone asks for. In those last two modes, @claude review always adds per-push cost for that PR.
• Cap managed Code Review with a monthly spend cap at claude.ai/admin-settings/usage. The repositories table in admin settings shows average cost per review, and the analytics dashboard breaks spend down by repository.
• Cap the Action: set --max-turns in claude_args, add a workflow timeout, and use GitHub's concurrency controls.
• Match depth to the change: local /code-review while you iterate, ultrareview for substantial changes before merging.

A review setup that works

1. Run /code-review locally before pushing.
2. Run one automatic review per PR, through managed Code Review or the Action, with a focused REVIEW.md.
3. Use ultrareview, or @claude review always, for risky changes such as auth, billing or migrations.
4. Have a person approve every merge, focusing on intent, design and anything tagged pre-existing.

The same approach applies when agents write the code as well as review it: review each piece as it finishes, then review everything going out together before production. That's how Atlas runs its AI engineering team. Every build is reviewed as it finishes and comes back either RELEASABLE or with fix tasks filed to its builder by name, and before a production release everything going out is reviewed together.

Conclusion

Claude Code's reviewers look for correctness problems in the context of the wider codebase. They won't block merges, judge product intent or replace a human approval. Start with one review per PR and a short REVIEW.md that defines Important for your repo, add a merge gate only if you need one, and save ultrareview for changes where a missed bug would cost the most.

To run Claude Code headless in CI, call claude -p "<prompt>" and set the permissions yourself. Add --bare so the run ignores any hooks, MCP servers and CLAUDE.md it finds on the runner. Choose a permission mode such as dontAsk, and use --allowedTools to list only the tools the job needs. Request --output-format json so your pipeline can parse the result, and branch on the exit code.

This guide covers each of those settings and the problems that appear when nobody is around to answer a permission prompt. The flags come from Anthropic's documentation on running Claude Code programmatically and from its CLI reference. For Codex, including approval modes and sandboxing, see our Codex CLI setup guide.

How Claude Code non-interactive mode works

Add -p (or --print) to a claude command to run it non-interactively. Claude Code takes the prompt, works on it, prints the result and exits:

claude -p "What does the auth module do?"

Three behaviours matter in CI:

• Exit codes. Claude Code exits with 0 on success and with a non-zero code when the run fails, so your script can branch on the status. An invalid flag produces an error on stderr before the run starts. A failure during the run, such as missing authentication, is printed as the result on stdout. Text on stdout doesn't mean the run succeeded, so check the exit code.
• Stdin works. You can pipe data in and redirect the answer out. Piped stdin is capped at 10MB. Past that limit, Claude Code exits with an error and a non-zero status. For larger inputs, write the content to a file and give its path in the prompt.
• Some commands are unavailable. Skills and custom commands still work if you put /skill-name in the prompt. Built-in commands that only run in the terminal interface, such as /login, don't.

Piping also cuts down the permissions a job needs. The docs show a package.json script that pipes a diff into Claude, so Claude doesn't need Bash permission to read it:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p \"you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.\""
  }
}

If your pipeline can collect the data itself, pass the data to Claude rather than giving Claude a tool to fetch it.

Use bare mode so runs are reproducible

Without extra flags, claude -p finds and loads the same things an interactive session would: hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory and CLAUDE.md, from both the working directory and ~/.claude.

This matters most in CI. According to the documentation, a -p session without --bare runs the hooks in a project's .claude/settings.json and connects the servers in its .mcp.json, even in a folder you have never trusted. It shows no workspace trust dialog and asks for no approval per server. So if your pipeline checks out code you don't control, such as a pull request from a fork, that repository's configuration runs on your runner.

--bare skips all of that loading:

claude --bare -p "Summarize README.md" --allowedTools "Read"

There is one exception. For a directory you add with --add-dir, bare mode still loads skills from its .claude/skills/ folder, but it skips that directory's .claude/commands/ and .claude/agents/.

In bare mode, Claude has the Bash, file read and file edit tools. Any other context has to be passed with a flag:

Bare mode also changes how the session behaves:

• Only MCP servers given on the command line connect.
• Background tasks don't run, so a command that reaches its timeout stops instead of moving to the background.
• Claude doesn't get the system reminders that normally come with tool results. For example, it isn't told when a file it read earlier has changed on disk.

Before v2.1.286, these limits were only partly in place.

Anthropic recommends --bare for scripted and SDK calls and says it will become the default for -p in a future release. Setting it now means your jobs won't change behaviour when that happens.

Authentication in bare mode

Bare mode never reads OAuth credentials or the system keychain, so a subscription login on the runner won't work. For the Anthropic API, set ANTHROPIC_API_KEY in the environment to a key created in the Claude Console, or supply an apiKeyHelper in the --settings JSON. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry still read their own provider credentials. Keep the key in your CI system's secret store, not in the workflow file.

Safe permissions for unattended runs

In a headless run, nobody can answer a prompt. Decide in advance what is allowed, and make sure everything else is denied. Otherwise a run can hang, or be approved by a mode you didn't choose.

Always set a permission mode

If nothing sets a permission mode, the run starts in Claude Code's built-in starting mode, which can be auto. Pass the mode you want explicitly. The headless docs describe three options:

• dontAsk denies every call that would otherwise prompt, and the docs suggest it for locked-down CI runs. Actions that need no approval in Manual mode still run, such as file reads in your working directories and the read-only command set. So do actions covered by your --allowedTools entries or permissions.allow rules. Some things are denied even when an allow rule matches, including AskUserQuestion and reads from network paths.
• acceptEdits lets Claude write files without prompting and auto-approves common filesystem commands such as mkdir, touch, mv and cp. Other shell commands (apart from read-only ones) and network requests still need an allow rule.
• auto has a classifier review most actions in place of a person.

claude -p "Apply the lint fixes" --permission-mode acceptEdits

For most CI jobs, start with dontAsk and add allow rules one at a time. Use acceptEdits for jobs whose purpose is to change files, such as applying formatter or lint fixes on a branch.

Scope tools with allowedTools

--allowedTools approves specific tools ahead of time:

claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

A bare Bash entry approves shell commands without asking, which is usually more than a CI job needs. The flag uses Claude Code's permission rule syntax, so you can approve command prefixes instead:

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

The space before * matters. Bash(git diff *) matches commands that start with git diff. Without the space, Bash(git diff*) would also match git diff-index.

If a run starts in auto mode, Claude Code drops a bare Bash entry as a broad allow rule, and the classifier checks each command instead.

Turn prompts off completely

--permission-prompts none is meant for runs where nobody can answer. It needs Claude Code v2.1.259 or later, and earlier versions reject it as an unknown option. Permission rules, PermissionRequest hooks and the permission mode still decide each call first. Anything left that would prompt is denied, Claude is told that nobody can approve it and that it shouldn't retry, and the run continues. Tools that need a person's answer, such as AskUserQuestion, are removed:

claude -p "Update the dependency pins and run the tests" --permission-mode auto --permission-prompts none

In a plain -p run with no permission host, these requests are denied anyway, and the flag adds the instruction not to retry. The flag matters most in runs that do have a host, meaning an Agent SDK canUseTool callback or a --permission-prompt-tool. Without the flag, the run waits for that host to answer each request.

With stream-json output, each denial appears as a permission_denied system message, and the final result lists all of them in permission_denials. If you save that list as a CI artifact, you can see which rule to add or which request needs a closer look.

Get output your pipeline can parse

--output-format accepts text (the default), json or stream-json. The json format returns the result along with the session ID and other metadata. To get a fixed shape, add --json-schema. The answer then appears in structured_output:

claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

If the schema is invalid, claude exits with an error. The format keyword (for example "format": "email") is accepted as an annotation but not enforced, so validate those fields yourself.

The JSON payload also includes total_cost_usd and a cost breakdown per model. Anthropic describes these as client-side estimates that can differ from your actual bill. Use them to track spending, not as billing data.

A review job can add a role prompt and still keep the default system prompt:

gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json

Fail the build when a server or plugin didn't load

When you pass --mcp-config, Claude Code checks each entry at startup and skips invalid ones, such as a url entry with no type. The run then continues and exits cleanly. In a terminal you would see a warning on stderr. When a CI runner captures or redirects stderr, though, no warning is printed.

The skipped entries are then reported only in the system/init event, which you can read from stream-json output:

• mcp_server_errors lists skipped servers (v2.1.219 or later).
• plugin_errors lists plugins that failed to load.

Both keys are left out when there are no errors, so fail the job if either one is present and non-empty. Otherwise a review step can pass without the tool it depends on.

Keep runs bounded

CI jobs need limits on time and cost. The docs describe these controls:

• Background work. After its turn, a -p run can stay open while background work that Claude started finishes. By default, Claude Code stops whatever is still running after 10 minutes of continuous idle waiting and drops its partial result. Some work is exempt. For example, a background command started by the main conversation keeps the run open until the command exits or hits its own time limit. CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS changes the 10-minute cap, and setting it to 0 removes the cap. In bare mode, no background tasks run.
• Budget. --max-budget-usd stops the run once estimated spend reaches the amount you set. It checks against the client-side estimate, and spend can go past the cap, so leave headroom. Once the cap is reached, Claude Code also stops any remaining background work instead of waiting for it. --max-turns limits the number of agentic turns and exits with an error when the limit is reached.
• Cancellation. If your runner sends SIGTERM, Claude Code exits with code 143. The current turn is left unfinished with no result, Bash process trees are terminated, and SessionEnd hooks run. If you want the turn to end properly, send SIGINT first.

Multi-step jobs: resume by session ID

Some jobs work better in stages, such as reviewing first and summarising afterwards. Capture the session ID, then resume that session explicitly:

session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

Use --resume with an ID rather than --continue. --continue loads the most recent conversation in the current directory, which may not be the one you want when several jobs share a runner. After a resume, the reported cost covers the whole conversation, earlier runs included. Those earlier totals don't count toward --max-budget-usd.

A checklist for headless CI jobs

1. Use claude --bare -p, and load prompts, settings and MCP servers only through explicit flags.
2. Authenticate with ANTHROPIC_API_KEY (or your cloud provider's credentials) from the CI secret store.
3. Set --permission-mode yourself, starting with dontAsk.
4. In --allowedTools, use prefix rules like Bash(git diff *) instead of a bare Bash.
5. Pipe data in where you can, so Claude needs fewer tools.
6. Use --output-format json, add --json-schema when later steps depend on the output's shape, and check the exit code.
7. Fail the job on non-empty mcp_server_errors or plugin_errors, and save permission_denials.
8. Set --max-budget-usd with headroom, plus a job timeout in your CI system.
9. Pin the Claude Code version on your runners, for example with claude install <version>.

The same principles apply when you run many agents instead of one. Atlas runs each engineer as its own Claude Code session with a written role and its own working folder. It leaves production go-lives, spending, deleting data and sending anything outside to a person.

Summary

Running Claude Code headless comes down to two things. Make each run independent of the machine it lands on, and make permissions an explicit allowlist instead of relying on a default. --bare, an explicit --permission-mode, narrow --allowedTools rules and JSON output cover most of that. The other checks catch failures that would otherwise go unnoticed: the exit code, mcp_server_errors and permission_denials.

Several behaviours described here depend on recent versions, including --permission-prompts (v2.1.259) and the full bare-mode limits (v2.1.286). Pin your version, and reread the programmatic usage docs whenever you upgrade.

Use Claude Code subagents when a side task would fill your main conversation with output you won't look at again, when a job needs tighter tool limits than your session has, or when you want a reviewer that didn't write the code. A subagent is a Markdown file with YAML frontmatter in .claude/agents/ or ~/.claude/agents/. Only name and description are required. Everything else (tools, model, permissions, hooks, memory and so on) is optional, but each one is worth a deliberate choice.

This guide covers when splitting work pays off, how to write a definition Claude actually delegates to, and the configuration mistakes that fail without an error.

What a Claude Code subagent is

A subagent runs in its own context window with its own system prompt, tool access and permissions. Claude hands it a task, it works independently, and it returns a result, usually a summary. Only that result comes back into your main conversation.

What matters more is what a fresh (non-fork) subagent sees. According to the docs, it starts with:

• its own system prompt plus basic environment details such as the working directory, not the Claude Code system prompt
• the delegation message Claude wrote for it
• your CLAUDE.md files, unless the definition sets omitClaudeMd
• a git status snapshot
• the full content of any skills listed in its skills field
• a list of main and the other named agents in the session

The built-in Explore and Plan agents skip CLAUDE.md and the git status snapshot to keep research fast and cheap.

A subagent does not get your conversation history, your output style or the main conversation's auto memory. The task prompt has to carry everything. If you agreed on a constraint twenty messages ago, the subagent won't know it unless the delegation prompt repeats it.

Subagent requests count toward the same usage limits as your main conversation. Splitting work doesn't make it free.

When to split work into a subagent

Split when:

• The output is noisy. The best-practices guide notes that a single debugging session or codebase exploration can use tens of thousands of tokens. Its advice: prompt "use subagents to investigate X" so the reading happens in a separate context and only summaries come back.
• You want enforced limits. A read-only reviewer, or a database agent that may only run SELECT, should have those limits in configuration, not just in the prompt.
• You want an independent check. A reviewer in a fresh context sees only the diff and the criteria you give it, not the reasoning that produced the change.
• The task is self-contained. If it fits in one prompt and can be answered with a summary, it's a good candidate.
• You keep needing the same kind of worker. That's the point to save a definition instead of re-typing the instructions.

Keep it in the main conversation when:

• you're iterating back and forth and each step depends on the last
• several phases, such as planning, implementation and testing, share a lot of context
• the change is quick and targeted
• latency matters, because a fresh subagent may need time to gather context

If you want a reusable prompt that runs in your main context, use a skill instead. For a quick question about something already in the conversation, use /btw: it sees your context but has no tool access, and its answer isn't added to history.

Start with the built-in subagents

Claude Code ships with:

• Explore: fast, read-only codebase search. Claude picks a thoroughness level of quick, medium or very thorough.
• Plan: a read-only research agent used in plan mode.
• General-purpose: every tool available to subagents, for multi-step tasks that need both exploration and action.

Explore and Plan are denied Write and Edit. A plain prompt such as "use subagents to investigate how token refresh works" often needs no custom definition. Write your own when you need a specific role, tool set or model.

How to define a subagent

Where the file lives

When names collide, the higher-priority location wins:

Project agents are found by walking up from the current working directory to the repository root, and agent directories are scanned recursively, so subfolders such as agents/review/ work. If two files in the same directory tree declare the same name, only one loads, chosen by filesystem read order. /doctor reports these duplicates. Check project agents into version control so your team shares them.

A minimal, useful definition

This is the read-only code reviewer from the official examples, shortened (the full version also has a review checklist). It shows three habits: a narrow role, a restricted tool list and a prompt that says exactly what to output.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Claude Code watches the agent directories and picks up edits within a few seconds. You need a restart in three cases: after creating the first agent file in an agents directory that didn't exist when the session started, after changing agents in a directory added with --add-dir or /add-dir, and in sessions started with --disable-slash-commands.

Write the description for routing

Claude reads description to decide when to delegate, so write it as a routing rule:

• Make it specific enough to point to one subagent. Overlapping descriptions lead to the wrong pick.
• Add a phrase like "use proactively" if you want Claude to delegate without being asked.
• Keep it short and put detail in the body, which loads only when the subagent runs. Claude Code warns at startup when the combined descriptions of your non-built-in subagents exceed 15,000 tokens.

Restrict tools deliberately

If you leave out tools, the subagent inherits every tool available to subagents. tools is an allowlist and disallowedTools a denylist:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

If both are set, disallowedTools is applied first and tools is resolved against what remains. Two details:

• mcp__<server> grants or removes every tool from one MCP server. In disallowedTools, mcp__* removes all MCP tools.
• Bash(git push *) in disallowedTools removes the whole Bash tool, not just that command. To keep Bash and block specific commands, add a deny rule such as Bash(git push *) to permissions.deny in your settings. For finer, conditional checks, use a PreToolUse hook.

The docs' db-reader example takes the hook route. The agent gets Bash, and a PreToolUse hook in its frontmatter runs a script that reads the hook input as JSON from stdin and extracts the command. If it contains SQL write keywords such as INSERT, UPDATE, DELETE, DROP or ALTER, the script exits with code 2 and the command is blocked. On macOS and Linux the script must be executable, or the hook fails instead of blocking anything. The prompt tells the agent it is read-only; the hook is the backstop.

Choose a model and effort level per role

model accepts sonnet, opus, haiku, fable, a full model ID, or inherit. The docs suggest controlling costs by routing tasks to faster, lower-cost models like Haiku, which suits narrow work such as searching or summarizing logs. Reviewers and anything that reasons about design usually deserve a stronger model.

The model is resolved in this order: a model Claude passes for that invocation, then the frontmatter value, then the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then the main conversation's model. To force one model on every subagent (Claude Code v2.1.257 or later), set both variables:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

The effort field takes low, medium, high, xhigh or max; which levels are available depends on the model.

Other fields worth knowing

• permissionMode: ignored when the main session is in bypassPermissions, acceptEdits or auto mode; the subagent runs in that mode instead.
• maxTurns: caps the agent's turns. At the cap, output is returned marked as partial and Claude can resume the agent.
• skills: preloads the full content of listed skills (up to 32 names). Without it, the subagent can still find and invoke skills while it works.
• memory: user, project or local persistent memory. The docs recommend project as the default because it can be shared through version control.
• isolation: worktree: runs the subagent in a temporary git worktree; it is removed automatically if the subagent makes no changes.
• background: true: keeps the subagent in the background even when Claude asks for the foreground.

How to invoke a subagent

• Automatically: Claude matches the task to a description.
• By name: Use the code-reviewer subagent to review the auth changes
• @-mention: @"code-reviewer (agent)" look at the auth changes, or type @agent-<name>.
• Whole session: claude --agent code-reviewer. Unless its prompt is empty, the agent's prompt replaces the default Claude Code system prompt.
• Session-only: pass JSON with --agents, where prompt replaces the Markdown body, for example claude --agents '{"code-reviewer": {"description": "...", "prompt": "...", "tools": ["Read", "Grep"], "model": "sonnet"}}'.

When a background subagent needs permission for a tool, the prompt appears in your main session with the subagent's name; Esc denies that one call without stopping it. Press Ctrl+B to move a running task to the background. Resumed subagents keep their full history, except Explore and Plan, which are one-shot and can't be resumed.

Forks are a different tool

A fork inherits the whole conversation, system prompt, tools and model. Its first request reuses the main session's prompt cache, so it costs less than a fresh subagent when the task needs the same context. Start one with /subtask <task> (on v2.1.161 through v2.1.211 the command is /fork). Use a fork when the side task needs everything you've discussed; use a defined subagent for a clean slate and a specific role.

Add an adversarial reviewer

The best-practices guide recommends a review step before you count unattended work as done. For a plain bug check of the current diff, the bundled /code-review skill runs in a fresh subagent. To check against a plan, name the work, the standard and what counts as a finding:

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.

The guide also warns that a reviewer asked to find gaps will usually report some even when the work is sound. Chasing every finding leads to extra abstraction, defensive code and tests for cases that can't happen. Tell the reviewer to flag only gaps that affect correctness or the stated requirements.

Mistakes that fail silently

• Typos in frontmatter. Unrecognized field names are ignored without an error. Run claude --debug and search the session's log in ~/.claude/debug/ for does not recognize or apply.
• Missing fields or broken YAML. A file with no name is treated as documentation and never loads. A name with no description, or YAML that doesn't parse, is skipped with only a note in the debug log.
• Shorthand numbers. In autoCompactWindow, 200k is read as 200, outside the allowed range of 100,000 to 1,000,000. Write 200000.
• Assuming shared context. Repeat key constraints in the delegation prompt, including CLAUDE.md rules if the agent sets omitClaudeMd.
• Spawning without limits. By default subagents can nest up to three layers below the main conversation, and spawning fails once 20 are running. Change these with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH and CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Each extra subagent adds to token spend.

Subagents versus separate sessions

Subagents are workers inside one session; their results come back to a single orchestrator's context. For longer-lived roles, the next step is separate Claude Code sessions, each with its own working folder. Atlas works this way: each of its engineers is its own Claude Code session with a written role, its own working folder, and a model and effort level suited to the role. Either way, give each worker one clear job, the tools it needs and a defined deliverable.

Conclusion

Start with the built-in Explore agent and plain "use subagents to investigate…" prompts. Write a custom definition when you keep needing the same role. Keep the description short and specific, restrict tools in configuration rather than in the prompt, pick a model that fits the job, and put everything the agent needs in the task prompt. Add a fresh-context reviewer before trusting long unattended runs, and check the claude --debug log when a field doesn't seem to take effect.

Claude Code hooks are shell commands that Claude Code runs at fixed points in a session, such as before a tool call, after it, and when Claude finishes responding. They turn "please always run the formatter" from a request the model may forget into a rule that always runs. Three hooks cover most guardrail needs. A PreToolUse hook blocks risky commands and edits. A PostToolUse hook formats each edited file. A Stop hook keeps Claude working while tests fail.

This guide sets up all three, explains the exit codes and JSON that control them, and covers the mistakes that make a guardrail fail without telling you.

How Claude Code hooks work

You define a hook in a settings file under the hooks key. It has three levels: the event, a matcher group, and one or more handlers. The file you put it in decides who it applies to:

• ~/.claude/settings.json: all your projects, only on your machine.
• .claude/settings.json: one project, and you can commit it to the repo. Team guardrails go here.
• .claude/settings.local.json: one project, not shared.
• Managed policy settings: organisation-wide, controlled by admins.

When an event fires, Claude Code sends JSON to your command's stdin. For a Bash call, a PreToolUse hook gets tool_name and tool_input (tool_input.command holds the shell command). For Edit and Write, tool_input.file_path holds the target file as an absolute path.

Your command answers with its exit code:

• Exit 0: no objection. On PreToolUse this does not approve the call. The normal permission flow still applies.
• Exit 2: block. Write the reason to stderr. On PreToolUse, Claude gets it as feedback on why the call was blocked. On Stop, Claude gets it as the reason to keep working.
• Any other code: unless stdout holds valid JSON that decides the outcome, this is a non-blocking error and the action goes ahead.

The docs are explicit that exit 1, the usual Unix failure code, enforces nothing. If a hook enforces a policy, it must exit 2 or return a JSON decision.

All hooks that match an event run in parallel, and each one runs to completion even if another denies. For PreToolUse decisions the most restrictive result wins, in the order deny, defer, ask, allow. (defer only works in non-interactive -p mode.)

Block risky shell commands with PreToolUse

The docs show the basic pattern: read stdin, pull out the command, and exit 2 if it matches something you never want run. Here it is, extended to a short deny list. Save it as .claude/hooks/block-risky-bash.sh:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

for pattern in "rm -rf" "git push --force" "drop table"; do
  if echo "$COMMAND" | grep -qi -- "$pattern"; then
    echo "Blocked: '$pattern' is not allowed in this repo. Ask the user to run it." >&2
    exit 2
  fi
done

exit 0

Make it executable with chmod +x .claude/hooks/block-risky-bash.sh, then register it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-risky-bash.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIR is the project root where the session started, so the path still works after Claude changes directory. The scripts here use jq to parse JSON, so install it first.

Plain substring matching is easy to get around: rm -r -f or git push -f slip past this list. Treat it as a first line of defence and keep hard bans in permission rules (see below).

Write the stderr message for the model as well as for you. Claude reads it and adjusts, so "ask the user to run it" gives it more to work with than a bare "denied".

Deny with JSON when you want structured output

Instead of exiting 2, you can exit 0 and print a decision on stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database writes are not allowed"
  }
}

permissionDecision must sit inside hookSpecificOutput. If you put it at the top level, the JSON still parses, but Claude Code ignores the field without reporting an error. The docs advise picking one method per hook: exit 2 with stderr, or exit 0 with JSON.

Why a PreToolUse deny holds in every mode

PreToolUse hooks fire before any permission-mode check. A deny blocks the tool even in bypassPermissions mode or with --dangerously-skip-permissions. This matters most in unattended runs. If you run Claude Code from scripts or pipelines, pair these hooks with the permission settings covered in Claude Code Headless in CI.

The docs list one exception. A mod (a plugin whose code runs inside Claude Code) that handles tool.check can approve a call your PreToolUse hook blocked, unless the hook is in managed settings. Check what your installed mods do before you rely on a hook alone.

It does not work the other way. A hook that returns "allow" does not bypass deny rules in settings. Hooks in settings files can tighten restrictions but not loosen them past your permission rules.

Protect sensitive files from edits

The same approach works for file edits. The Claude Code hooks guide uses this script to block changes to .env, package-lock.json and anything in .git/:

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

Register it on PreToolUse with the matcher Edit|Write, the same way as the Bash hook. Claude can also change files from the shell, which this matcher does not see. The docs suggest two ways to catch every change: also match Bash|PowerShell and have the script list modified and untracked files with git status --porcelain, or add a Stop hook that scans the working tree once per turn.

Enforce formatting after every edit

Formatting belongs in a PostToolUse hook. It runs after the edit lands, so it can't prevent the edit, but it keeps the file tidy. This is the documented Prettier hook for .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

To use a different formatter, put its command after xargs. Two things to know:

• PostToolUse cannot undo an action, because the tool has already run.
• To push back after an edit, for example when a linter fails, return {"decision": "block", "reason": "..."}. The reason goes to Claude to read.

If you want a specific file reformatted however it changes, including by a Bash command, the docs point to the FileChanged event instead.

Make tests pass before Claude stops

A Stop hook fires whenever Claude finishes responding. If it blocks, Claude keeps working, and your exit-2 stderr (or JSON reason) tells it why. That makes it a good place for a test gate:

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi

if ! OUTPUT=$(npm test 2>&1); then
  echo "Tests are failing. Fix them before finishing:" >&2
  echo "$OUTPUT" | tail -n 40 >&2
  exit 2
fi

exit 0

Save it as .claude/hooks/require-tests.sh and register it under "Stop". Stop does not support matchers, so leave the matcher out:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/require-tests.sh"
          }
        ]
      }
    ]
  }
}

The stop_hook_active check matters. The field is true when Claude is already continuing because a stop hook blocked. Claude Code also has a hard cap: after a Stop hook blocks eight times in a row with no tool call from Claude in between, Claude Code overrides it and ends the turn. You can raise the cap with the CLAUDE_CODE_STOP_HOOK_BLOCK_CAP environment variable. With the early exit on stop_hook_active, this script blocks once per stop attempt rather than looping on a test that can never pass.

Two more points:

• Stop fires at the end of every response, not only when a task is complete. Keep the test command fast, or run only the affected suite.
• Command hooks time out after 10 minutes by default. Set timeout in seconds if you need a different limit.

The docs also show an agent-type Stop hook that runs the test suite itself. Agent hooks are marked experimental, and the docs recommend command hooks for production workflows.

Make guardrails fail closed

By default, if a hook fails (it can't start, times out, or exits with a code other than 0 or 2 without a JSON decision), Claude Code reports a non-blocking error and the action goes ahead. On PreToolUse, a hook that times out does not block the tool call. That's fine for formatting but wrong for a policy hook. Add "onFailure": "block" to the hook so a failure does what exit 2 would do on that event. It needs Claude Code v2.1.295 or later. It has no effect on Stop hooks or on async hooks.

Hooks also run alongside Claude Code's permission system, not in place of it. The docs describe the if filter (for example "if": "Bash(git *)", which limits when a hook runs) as best-effort, and recommend the permission system for a hard allow or deny. Use both:

• Put absolute bans in permission deny rules.
• Use PreToolUse hooks for checks that need logic, such as patterns, file paths or project state.
• Use PostToolUse and Stop hooks to enforce quality.

Rules you'd like Claude to follow but that don't need enforcing belong in your project instructions file. CLAUDE.md Best Practices covers how to write them.

Test and debug your hooks

• Run /hooks inside Claude Code to see every configured hook, grouped by event.
• Test a script without Claude by piping sample JSON into it:

echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
echo $?  # Check the exit code

• If you see "command not found", use ${CLAUDE_PROJECT_DIR} or absolute paths. If you see "jq: command not found", install jq. If the script doesn't run at all, make it executable with chmod +x.
• If your JSON has no effect and no error appears, check two things. Your shell profile may be printing text before the {, so Claude Code reads the output as plain text. Or a field may be at the wrong level. Start claude --debug and search the debug log.
• Edits to hooks in settings files are normally picked up automatically. If they don't show up in /hooks after a few seconds, restart the session.

Commit .claude/settings.json and .claude/hooks/ together, so everyone on the team and every CI run gets the same guardrails.

Where to start

Hooks are the part of Claude Code that doesn't rely on the model remembering anything. Start with a PreToolUse deny list for commands and files you never want touched, add a PostToolUse formatter, then a Stop hook that runs your tests and respects stop_hook_active. Make policy hooks exit 2, set onFailure: "block" on your PreToolUse guardrails, and keep absolute bans in permission rules. The same idea applies beyond one session: on Atlas, each engineer runs as its own Claude Code session, and completion is refused until the work is on main or queued for the landing train and the product's rules pass.

Claude Code and OpenAI Codex do the same core job. They read a repository, edit files, run commands and propose changes. Over the past year their feature lists have grown closer together. Both now have an instruction file, project-level config, hooks, subagents, MCP support, a non-interactive mode for scripts, cloud tasks and pull request review. So the choice between them comes down to how each one handles safety, sharing settings, delegation and access, more than to any feature only one of them has.

This comparison covers those workflow questions. Model quality changes with every release, so it isn't covered here.

Claude Code vs Codex at a glance

Both tools change quickly. Check the official docs (linked at the end) before you standardise on a flag or file layout.

Getting both tools running

Anthropic recommends Claude Code's native installer. On macOS, Linux and WSL:

curl -fsSL https://claude.ai/install.sh | bash
claude

Homebrew (brew install --cask claude-code) and WinGet also work, but those installs don't update automatically.

You can install Codex with npm, Homebrew (brew install --cask codex) or an install script:

npm install -g @openai/codex
codex

Each tool asks you to sign in the first time it runs. For a fair trial, give both the same three or four real tickets from your backlog: one bug fix, one small feature, one refactor and one task that needs the test suite. Then compare the diffs, how often you had to step in, and how much reviewer time each change needed.

Project instructions: CLAUDE.md vs AGENTS.md

Every team ends up writing down the same things: how to run tests, which directories not to touch, naming conventions and commit format.

• Claude Code reads CLAUDE.md at the start of every session. You can have one at the project root, one for your own use in ~/.claude/, and more in subdirectories. If the repository already has an AGENTS.md, Claude Code can read that instead. The docs point out that CLAUDE.md is context, not enforced configuration. To block an action whatever the model decides, use a hook.
• Codex reads AGENTS.md from ~/.codex, then from each directory between the project root and your current directory, with closer files taking precedence. An AGENTS.override.md replaces the regular file in its directory. The combined files are capped at 32 KiB by default.

Because Claude Code can read AGENTS.md, a team that uses both tools can keep a single instruction file. Treat it like code: review changes in pull requests, keep it short, and delete rules the agent already follows without being told.

Permissions and safety

This is where the two tools feel most different.

Claude Code: rules and modes

Claude Code has allow, ask and deny rules for tools and command patterns. Settings can be checked into version control so every developer shares them, and each developer can still add their own. On top of the rules sits a permission mode. In default (Manual) mode it asks before most actions except reads. acceptEdits allows file edits and common filesystem commands without asking. plan reads and explores but doesn't edit source code. In auto mode, a second model (a classifier) reviews actions instead of you. From Claude Code v2.1.283, auto mode is the starting mode for interactive terminal and VS Code sessions, so if your team wants a different default, set it explicitly.

Codex: sandbox plus approval policy

Codex separates two questions. The sandbox (sandbox_mode) controls what the agent can technically reach: read-only, workspace-write or danger-full-access. The approval policy (approval_policy) controls when it stops to ask: on-request or never. The docs give this as the low-friction preset for local work:

codex --sandbox workspace-write --ask-for-approval on-request

A separate setting, approvals_reviewer, can send eligible prompts to a reviewer agent instead of you. All of these can be set in config.toml instead of on the command line.

What to standardise

Whichever tool you pick, write down a team default and commit it:

• Which commands may run without asking (tests, linters, type checks).
• Whether network access is allowed during agent runs.
• What is never allowed (production deploys, secret files, force pushes).

If every developer configures this differently, nobody can say afterwards what an agent was allowed to do.

Shared configuration and automation

Both tools have a non-interactive mode for scripts and CI:

claude -p "Summarise the failing tests in this branch and suggest a fix"
codex exec "Summarise the failing tests in this branch and suggest a fix"

codex exec runs in a read-only sandbox by default. Add --sandbox workspace-write if the job needs to edit files. For GitHub workflows, OpenAI recommends its Codex GitHub Action over installing the CLI in a shell step.

The building blocks for shared behaviour are now similar:

• Hooks. Claude Code hooks run commands at lifecycle events such as PreToolUse and PostToolUse, and a PreToolUse hook can block a tool call. Codex has hooks too, with events such as PreToolUse, PermissionRequest and Stop. They can be set at user or project level. Codex runs non-managed hooks only after you have reviewed and trusted them with /hooks.
• Subagents. Claude Code subagents are Markdown files in .claude/agents/, each with its own instructions, tool limits and context window. Codex custom agents are TOML files in .codex/agents/, each with its own instructions, model and reasoning effort. They inherit sandbox and approval settings from the parent session.
• Skills. Both tools package repeatable workflows as skills. In Claude Code, project skills live in .claude/skills/, and the older .claude/commands/ files still work.
• MCP. Both connect to external tools and data through Model Context Protocol servers, so an issue tracker or docs server can serve both.

One practical difference is how project config is trusted. Claude Code's .claude/settings.json is meant to be shared with everyone in the project. Codex loads a project's .codex/ layers (config, hooks, rules) only after the project is marked as trusted. Codex profiles let you switch between named sets of settings with --profile.

Delegation: cloud tasks on both sides

Both tools can now run work away from your laptop.

Codex Cloud runs tasks remotely. You set up an environment in which Codex inspects your repositories, installs dependencies and tests the workflow. Then you start tasks from it. Each task has its own workspace and keeps running while your computer is asleep. You review the changed files, ask for follow-ups, and commit or open a pull request.

Claude Code cloud sessions run on Anthropic-managed VMs. You can start them from claude.ai/code, the mobile app, the desktop app or the terminal with claude --cloud "<task>". Each --cloud command starts its own independent session, so you can run several in parallel. claude --teleport pulls a cloud session back into your terminal. Cloud sessions are available on Pro, Max and Team plans, and for some Enterprise seats. For local parallel work, Claude Code also supports background agents.

Things to weigh:

• Environment fidelity. Cloud tasks need your setup (dependencies, services, seed data) to be reproducible remotely. If your build only works on a developer's laptop, local sessions will be easier at first.
• Secrets and network. Both tools let you limit network access in cloud environments and add credentials for allowed services. Decide which credentials a remote environment may hold. Often the right answer is none.
• Review load. Parallel agents produce many diffs. The bottleneck moves from writing code to reviewing it.

Code review and pull requests

Codex starts a review when someone comments @codex review on a pull request, and it can review pull requests automatically once automatic reviews are enabled. Claude Code's GitHub Action responds to @claude in issues and pull requests, and its separate Code Review product reviews every PR automatically. With Claude Code cloud sessions, auto-fix can also watch a PR and push fixes for CI failures and review comments.

Agent review works as a first pass. It catches missed edge cases, tests that don't match the code and obvious security mistakes. It doesn't replace an owner who understands the system. A sensible team rule is that an agent's review can block a merge, but only a human can approve one.

Where each one fits

Choose Claude Code if

• You want detailed permission rules (allow, ask, deny) and one settings file the whole team commits.
• You want hooks that run without a separate trust step, and subagents with their own tool limits.
• You already pay for Claude plans, use the Anthropic API, or need a third-party provider in the CLI.

Choose Codex if

• You prefer safety split into two settings: a hard sandbox boundary and an approval policy.
• Your team already works in ChatGPT workspaces, where Codex is included from the Free plan up.
• You want project config and hooks to load only once someone has marked the project as trusted.

Using both

Some teams use one tool for interactive work and the other for delegated tasks, or have both review the same pull request. If you do this, keep one instruction file (Claude Code can read AGENTS.md) and one written permissions policy that you turn into each tool's config. Otherwise you end up maintaining two sets of rules that drift apart.

The workflow problem neither tool solves alone

Both tools give you a capable agent and can run several at once. Neither one gives you a team process: who owns which task, what counts as "done", when work may merge, and who approves a release. When teams run several agents, this missing layer is usually what breaks first. Two agents edit the same files, or a change is called finished without passing tests.

Some teams build that layer with scripts, worktrees and CI rules. Others use tools built on top of the agents. Atlas, for example, runs on Claude Code. Each engineer role is its own Claude Code session with a written role and its own working folder. Atlas refuses to mark work complete until it is on main or queued for its landing train, which merges finished branches and runs the project's own checks on the result. Whatever you choose, define "done" before you increase the number of agents.

Conclusion

Claude Code and Codex now offer much the same set of features, so the choice comes down to workflow. Claude Code uses permission rules and modes, and its settings are shared through a committed file. Codex splits safety into a sandbox and an approval policy, and loads project config only from trusted projects. Run both on the same real tickets for a week, write down your permission defaults and instruction file, and measure reviewer time rather than how good the output looks at first glance.

To set up OpenAI Codex CLI, install it, run codex in a project folder, and sign in with your ChatGPT account or an API key. Then decide how much Codex may do without asking you. Two settings control that. The sandbox mode limits what its commands can touch. The approval policy decides when it has to stop and ask. This guide covers both, plus a config.toml and profile files you can reuse.

Codex has changed a lot in recent releases. --full-auto and the untrusted approval policy are gone, and profiles have moved into separate files. Many older guides still show the earlier syntax, so this one points out where things changed.

What Codex CLI is

Codex CLI is OpenAI's coding agent for the terminal. It is open source under the Apache-2.0 licence, in the openai/codex repository on GitHub. It reads your repository, edits files and runs commands such as tests and builds. Because it acts on your machine, the sandbox and approval settings matter more than which model you pick.

Installing Codex CLI

On macOS and Linux, the standalone installer is:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Running the same command again updates Codex. You can also install it with a package manager:

npm install -g @openai/codex
# or, on macOS
brew install --cask codex

On Windows, there is a PowerShell installer:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

The GitHub releases page also has prebuilt binaries for macOS (Apple silicon and Intel) and Linux (x86_64 and arm64). Each archive contains one file with the platform in its name, so you will usually rename it to codex after extracting it.

Signing in

Start Codex from the root of a project:

cd my-project
codex

On first run, Codex asks how you want to authenticate:

• Sign in with ChatGPT. Usage comes out of your ChatGPT plan, and you don't need to manage API keys.
• Use an API key. OpenAI bills this usage to your OpenAI Platform account at standard API rates. OpenAI recommends API keys for automation such as CI jobs.

You can also sign in without starting a session. codex login opens a browser for the ChatGPT sign-in, and --with-api-key reads a key from standard input:

codex login
printenv OPENAI_API_KEY | codex login --with-api-key

Approval policy vs sandbox mode

Setup often goes wrong because people treat these as one setting. There are two:

• Sandbox mode is enforced by the operating system. It limits which files Codex's commands can write and whether they can reach the network. If the sandbox blocks something, it stays blocked, whatever the model decides.
• Approval policy decides when Codex stops for your OK, for example before it goes outside the sandbox.

A tight sandbox with few prompts is often safer than a loose sandbox with many prompts. If you're asked to approve something every few seconds, you will soon start approving without reading.

Sandbox modes

Set the sandbox mode with --sandbox (or -s):

codex --sandbox read-only
codex --sandbox workspace-write

workspace-write is the default for local work. Codex can edit your project and run your test suite, but it can't write outside the workspace, and it has no network access unless you turn it on.

How the sandbox is enforced

Codex uses operating-system features to enforce the sandbox, so it doesn't depend on the model following instructions:

• macOS: Apple's built-in Seatbelt framework. It works without any setup.
• Linux and WSL2: bubblewrap (bwrap) together with seccomp. The docs say to install bubblewrap with your package manager first. Otherwise Codex falls back to a bundled helper, which needs unprivileged user namespaces.
• Windows: the native Windows sandbox when you run Codex in PowerShell. Under WSL2, Codex uses the Linux sandbox. WSL1 support ended with version 0.115.

The limits apply to the commands Codex runs, including test scripts and install commands. If your environment can't provide these features, run Codex inside a container or VM that is already isolated, and loosen Codex's own sandbox only there.

Approval policies

Set the approval policy with --ask-for-approval (or -a). The CLI accepts two values:

• on-request: Codex edits and runs commands inside the sandbox, and asks before it goes outside it, for example to use the network.
• never: Codex never asks. If the sandbox blocks something, the action fails.

codex --sandbox workspace-write --ask-for-approval on-request

In config.toml there is also a granular form. It keeps some kinds of approval prompt interactive and rejects the rest automatically.

Two older values no longer work. untrusted has been retired, and OpenAI says to remove it from your config. For cautious interactive use, it suggests read-only with on-request. on-failure is deprecated. The config reference says to use on-request for interactive runs and never for runs nobody is watching.

Shortcut flags

• --sandbox workspace-write --ask-for-approval on-request is the "Auto" preset. Codex works inside the project and asks only when it needs to go further. This suits most day-to-day coding in a repository under version control.
• --approve-for-me (alias --not-so-yolo) uses the workspace-write sandbox with on-request approvals, but sends approval requests to an automatic review step instead of to you.
• --dangerously-bypass-approvals-and-sandbox (alias --yolo) runs every command without approvals and without a sandbox. The docs say to use it only inside an environment that is already hardened, such as a throwaway container or VM.

--full-auto is no longer supported. If an old script uses it, replace it with --sandbox workspace-write or --approve-for-me.

In a session, /permissions lets you change when Codex can edit files or run commands without asking, and shows the current sandbox and the folders it can write to. /status shows the session's current configuration.

A practical config.toml

Flags are fine for one-off runs. For settings you want every time, use ~/.codex/config.toml:

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

Network access is already off by default. Setting it explicitly makes the choice visible to anyone reading the file.

This example doesn't set model, so Codex uses its default. To pin a model, add model = "..." with a model your account or workspace can use.

Codex also has newer permission profiles. You define them under [permissions.<name>] and select one with default_permissions. They can set rules per path, such as denying .env files, and limit network access to a list of allowed domains. They don't combine with sandbox_mode or [sandbox_workspace_write], so choose one approach per config.

Profiles for different levels of trust

Profiles let you keep several setups and choose one for each run. Since Codex 0.134.0, each profile is its own file in ~/.codex, named <profile>.config.toml. It uses top-level keys and contains only the values that differ from your base config. --profile no longer reads [profiles.<name>] tables in config.toml, so move any you have into separate files.

~/.codex/review.config.toml:

approval_policy = "on-request"
sandbox_mode = "read-only"

codex --profile review

A read-only review profile works well when you're exploring an unfamiliar codebase or asking Codex to explain code. Run without the profile when you want it to make changes under the base config.

One-off overrides

You can override any config key for one run with -c:

codex -c sandbox_workspace_write.network_access=true

Use this when a task needs the network, such as installing a dependency, instead of turning network access on for every run.

Project instructions with AGENTS.md

Codex reads AGENTS.md files before it starts any work. It reads a global one from ~/.codex, then walks from the project root (usually the git root) down to your current directory, reading the AGENTS.md in each folder along the way. Running /init in a session creates one for you to edit.

Keep it short and concrete:

• The exact commands for install, lint, test and build
• Directories that are generated or vendored and shouldn't be edited
• Conventions a reviewer would otherwise flag

Running Codex without the interactive UI

For scripts and CI, codex exec (alias codex e) runs a task and exits:

codex exec "explain why the test suite is failing"

By default, codex exec runs in a read-only sandbox, so Codex can't edit files. To let it make changes, grant write access explicitly:

codex exec --sandbox workspace-write "update the changelog for the latest commits"

In CI, set the API key only on the command that needs it, not for the whole job:

CODEX_API_KEY=<api-key> codex exec --json "triage open bug reports"

The docs warn against setting OPENAI_API_KEY or CODEX_API_KEY at job level when the job runs code from the repository, because build scripts or tests in that job could read the key. Keep the sandbox as narrow as the job allows. Nobody is reading prompts in a pipeline.

Choosing settings: a simple ladder

If you're not sure where to start, work up this list:

1. Exploring: read-only with on-request. Codex can read and explain code, but it can't change anything unless you approve it.
2. Everyday coding: workspace-write with on-request, network off. Commit before each session so git diff shows exactly what changed.
3. Tasks that need the network: the same setup, plus -c sandbox_workspace_write.network_access=true for that run only.
4. Fully unattended: --yolo only inside a disposable container or VM, never against your laptop's home directory.

Two habits matter more than the exact setting. Work on a clean git branch so you can review and revert any change. And read each command before you approve it, because approval prompts only protect you if someone reads them.

Beyond a single agent

Approval policies govern one agent, one action at a time. When several agents work on the same product, you also need rules at the project level, such as who approves a production release and who can spend money or delete data. Atlas, a team of AI engineers built on Claude Code, never makes those decisions itself: production go-lives, spending, deleting data, sending anything outside and dropping scope always go to a person.

Summary

Installing Codex CLI takes a few minutes: install it, run codex, sign in. Most of the setup is choosing the sandbox (what Codex can touch) and the approval policy (when it asks), then saving both in ~/.codex/config.toml. For most projects, start with workspace-write, on-request and network off. Add a read-only profile file for exploring, and use the full bypass only in a disposable environment. Flags have been renamed and removed recently, so check codex --help for your installed version before you put a flag in a script.

A good CLAUDE.md is short and specific. It holds what Claude Code can't work out from your code: the exact build and test commands, style rules that differ from the defaults, repository etiquette, and the gotchas people keep running into. Three kinds of content belong elsewhere: anything Claude can learn by reading the code, anything that applies to only one corner of the repo, and anything that must happen every time without exception.

This guide follows Anthropic's Claude Code documentation. It covers where the file goes, what to put in it, what to leave out, and what to check when Claude ignores it.

What CLAUDE.md is and isn't

Every Claude Code session starts with a fresh context window. CLAUDE.md is a Markdown file you write, and Claude reads it at the start of every session, so you don't have to explain your project again each time.

Claude treats CLAUDE.md as context, not enforced configuration. According to the documentation, the content is "delivered as a user message after the system prompt," and Claude tries to follow it, "but there's no guarantee of strict compliance, especially for vague or conflicting instructions." So whether your conventions get followed depends on two things: how clearly you write them, and whether hard requirements live somewhere that enforces them.

Where to put CLAUDE.md files

Claude Code reads instruction files from several places. They load from the broadest scope to the most specific:

Files are concatenated, not overridden. Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it. Files closer to where you launched Claude are read last, and within each directory CLAUDE.local.md comes after CLAUDE.md. A CLAUDE.md in a subdirectory below your working directory isn't loaded at launch. It loads once Claude reads, writes or edits a file in that subdirectory.

If you use git worktrees, note that a gitignored CLAUDE.local.md exists only in the worktree where you created it. To share personal instructions across worktrees, import a file from your home directory instead (imports are covered below).

Start with /init, then cut it down

Run /init in a session to generate a first draft. Claude analyzes your codebase and writes a file with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting it. It also reads Cursor rules (.cursor/rules/ or .cursorrules) and Copilot instructions (.github/copilot-instructions.md) and brings the relevant parts into the draft. For an interactive version, set CLAUDE_CODE_NEW_INIT=1 before running /init. It asks which artifacts to set up (CLAUDE.md files, skills and hooks), asks follow-up questions, and shows you a proposal before it writes any files.

Treat the draft as a starting point. The documentation says to refine it "with instructions Claude wouldn't discover on its own." Begin by cutting anything Claude could work out from the repository.

What to put in CLAUDE.md

Anthropic's best-practices guide has an include/exclude table. The include side:

• Bash commands Claude can't guess. Your real test, lint, typecheck and build commands, with the flags your project needs.
• Code style rules that differ from defaults. Skip anything the language's standard conventions already cover.
• Testing instructions and preferred test runners.
• Repository etiquette. Branch naming and pull request conventions.
• Architectural decisions specific to your project.
• Developer environment quirks, such as required environment variables.
• Common gotchas: behavior that isn't obvious from reading the code.

The memory documentation also says when to add a line: Claude makes the same mistake a second time, a code review catches something Claude should have known, you type a correction you already typed last session, or a new teammate would need the same context to be productive.

Write instructions you can check

The docs recommend instructions "concrete enough to verify," with these examples:

• "Use 2-space indentation" rather than "Format code properly"
• "Run npm test before committing" rather than "Test your changes"
• "API handlers live in src/api/handlers/" rather than "Keep files organized"

Group related rules under Markdown headings and bullet points. No format is required. The example in Anthropic's guide is this short:

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

What to leave out

The exclude side of the table:

• Anything Claude can figure out by reading the code
• Standard language conventions Claude already knows
• Detailed API documentation (link to it instead)
• Information that changes frequently
• Long explanations or tutorials
• File-by-file descriptions of the codebase
• Self-evident practices like "write clean code"

For each line, the guide suggests asking: "Would removing this cause Claude to make mistakes?" If not, cut it. The guide warns: "Bloated CLAUDE.md files cause Claude to ignore your actual instructions!" If Claude already does something correctly without an instruction, delete the instruction or turn it into a hook.

Keep it under 200 lines

The documented target is under 200 lines per CLAUDE.md file, because longer files consume more context and reduce adherence. Claude Code shows a warning at startup and in /status when one of your instruction files is over the recommended length. It also warns when several files that are each within that length add up past a combined limit. Each CLAUDE.md, rules file and @path import counts as a separate file. Files over 4 MiB are skipped entirely.

Two commands help with trimming. /doctor proposes cuts for a checked-in CLAUDE.md. It removes content Claude can derive from the codebase, such as directory layouts, dependency lists and architecture overviews, and keeps pitfalls, rationale and conventions that differ from tool defaults. /doctor prompt-audit (Claude Code v2.1.283 or later) checks your instruction files for problems: instructions written for older models, references to files or commands that don't exist, and files that contradict each other. It reports findings with proposed edits and changes nothing until you ask Claude to apply them.

Move the rest into rules, imports, skills and hooks

Content that isn't needed in every session can go somewhere else.

Path-scoped rules in .claude/rules/

Put one topic per file, such as testing.md or api-design.md, in .claude/rules/. A rule without a paths field loads at launch with the same priority as .claude/CLAUDE.md. If you add paths frontmatter, the rule loads only when Claude works with matching files:

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

This works well for conventions that apply to only part of a monorepo. Personal rules can go in ~/.claude/rules/ and apply to every project on your machine. If a user rule and a project rule conflict, Claude may follow either, so keep them consistent.

Imports with @path

CLAUDE.md can pull in other files with @path/to/file. Relative paths resolve relative to the file that contains the import, not the working directory. Imported files can import others, up to four hops deep:

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

Imports help organize a long file, but they don't reduce its context cost, because imported files also load at launch. To mention a path without importing it, wrap it in backticks. The first time Claude Code finds imports that point outside your working directory in a project, it shows an approval dialog listing them.

Skills for procedures

Multi-step procedures, and domain knowledge that only matters sometimes, belong in skills (.claude/skills/<name>/SKILL.md). A skill loads when you invoke it or when Claude decides it's relevant, so it doesn't take up context in every session.

Hooks for anything that must always happen

If a rule has to hold every time, such as running eslint after each file edit or blocking writes to the migrations folder, use a hook. In the best-practices guide's words, CLAUDE.md instructions are advisory, while hooks "are deterministic and guarantee the action happens." Organizations have the same split. Managed settings such as permissions.deny are enforced by the client, while a managed CLAUDE.md shapes behavior but is "not a hard enforcement layer."

Sharing one file with other coding agents

If your repository already has an AGENTS.md for other coding agents, Claude Code v2.1.277 or later reads it when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. If you want both files, the documented pattern is a CLAUDE.md that imports the shared file and then adds Claude-specific notes:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Watch out for one thing: a CLAUDE.local.md counts as having a CLAUDE.md, so adding one stops Claude from reading AGENTS.md by default. To keep both, open /config and set Project instructions to claude-md-and-agents-md.

When Claude ignores your CLAUDE.md

Work through these checks in order:

1. Confirm it loaded. Run /context and look under Memory files. If the file isn't listed, Claude can't see it. Subdirectory files don't appear there because they load on demand.
2. Look for conflicts. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.
3. Make the rule more specific. If Claude asks questions that CLAUDE.md already answers, the wording may be ambiguous.
4. Shorten the file. If Claude keeps doing something despite a rule against it, the guide says the file "is probably too long and the rule is getting lost."
5. Emphasize sparingly. If Claude keeps skipping one instruction, adding "IMPORTANT" to that line alone can help. Emphasize many lines and none stands out.
6. Check for built-in guidance. If your file sets commit or pull request rules, turn off Claude Code's own git instructions with the includeGitInstructions setting.

If an instruction disappears after /compact, it was probably given only in chat, or it lives in a nested CLAUDE.md or path-scoped rule that hasn't loaded again yet. Claude re-reads the project-root CLAUDE.md from disk after compaction, so moving a chat instruction into that file keeps it.

Two smaller details: block-level HTML comments (<!-- notes -->) are stripped before the content reaches Claude, so you can leave notes for human maintainers without spending context. And asking Claude to "remember" something saves it to auto memory, not CLAUDE.md. To put it in the shared file, say "add this to CLAUDE.md" or edit the file yourself through /memory.

When you run several agents

The same principles apply when several Claude Code sessions work on one codebase. Each session needs its role and constraints written down, and anything that must always hold needs a mechanism that enforces it, not just a sentence. Atlas follows this pattern. Each engineer is its own Claude Code session with a written role and its own working folder. "Done" is enforced: completion is refused until the work is on main or queued for the landing train.

Summary

The guide's advice is to treat CLAUDE.md like code. Generate a draft with /init, cut everything Claude could work out from the repository, and keep the rest concrete and under 200 lines. Move conventions that apply to only part of the codebase into path-scoped rules, procedures into skills, and steps that must always happen into hooks. Check the file into git, review it when Claude gets something wrong, and use /context to confirm what loaded.

To run several Claude Code sessions on one repository without them overwriting each other's edits, give each session its own git worktree. Claude Code does this with one flag, claude --worktree <name>. It creates a separate checkout on a new branch and starts the session inside it. This guide covers setup, the files a new worktree is missing, subagent isolation, cleanup, and the parts you still have to handle yourself.

Why parallel agents need git worktrees

Two agent sessions in one working directory share one set of files. One session's refactor can land in the middle of the other's test run, and both write to the same index. Separate branches don't solve this, because a single checkout can only have one branch checked out at a time.

A git worktree is an extra working directory linked to the same repository. Per the git documentation, each worktree gets its own HEAD and index. Refs under refs/, branches and tags included, are shared, apart from a few per-worktree ones such as refs/bisect. The repository's config file is also shared by default. What that means for you:

• A branch created or updated in one worktree is visible from all the others immediately, with no push or fetch.
• Each worktree has its own files on disk, so edits in one don't touch the others.
• By default, git worktree add refuses to check out a branch that's already checked out in another worktree. --force overrides this.

That last rule keeps agents apart: each session ends up on its own branch.

Start Claude Code in a worktree

Pass --worktree (or -w) with a name:

claude --worktree feature-auth

According to the Claude Code documentation, this creates the worktree under .claude/worktrees/feature-auth/ at the repository root, on a new branch named worktree-feature-auth, and starts the session there. Run the same command in a second terminal with a different name to get a second isolated session. If you leave out the name, Claude generates one, such as bright-running-fox. Pass a name whose directory already exists and Claude Code reopens that worktree rather than creating a new one.

There are two prerequisites:

• At least one commit. A worktree is created from an existing commit. In a repository with no commits, the command fails with Failed to resolve base branch "HEAD": git rev-parse failed.
• Workspace trust. Interactive runs need it. If you haven't used Claude in that directory before, run claude there once and accept the trust dialog. Non-interactive runs with -p skip this check.

Add the worktree folder to .gitignore so its contents don't show up as untracked files in your main checkout:

.claude/worktrees/

You can also ask Claude to "work in a worktree" during a session, and it creates one with its EnterWorktree tool. If Claude tries to enter a path outside the repository's .claude/worktrees/ directory, Claude Code asks for your approval first. Neither a permission rule nor "don't ask again" turns this prompt off. Only bypassPermissions mode skips it. The prompt arrived in v2.1.206. Before that, Claude could enter any existing worktree without asking. Several other behaviors in this guide also depend on recent 2.1.x versions, so on an older version some of them will work differently.

Choose what the worktree branches from

By default, a new worktree branches from the repository's default branch on the remote (usually main), so it starts from a clean tree. To branch from your current local HEAD instead, bringing along unpushed commits and feature-branch state, set worktree.baseRef in settings:

{
  "worktree": {
    "baseRef": "head"
  }
}

The setting has two values: "fresh" (the default) and "head". Inside a worktree, "head" means that worktree's HEAD, not the main checkout's. You can't set it to a branch name. To start from a specific existing branch, create the worktree with git yourself (see below).

To review or continue a pull request in isolation, pass its number with a # prefix. Quote it so your shell doesn't treat # as the start of a comment:

claude --worktree "#1234"

Claude Code fetches that pull request's head commit from origin and creates the worktree at .claude/worktrees/pr-1234. You can also pass a GitHub pull request URL or a GitLab merge request URL. Claude Code reads only the number from the URL and always fetches from origin.

Set up the worktree environment

A worktree is a fresh checkout of tracked files. It has none of your gitignored local files, so expect no node_modules, virtualenv, build cache or .env. Set up each worktree, either by asking Claude to install dependencies or by running your project's setup in the worktree directory yourself.

For gitignored files such as environment configs, add a .worktreeinclude file at the project root. It uses .gitignore syntax. Claude Code copies files that match a pattern and are gitignored into each new worktree, so tracked files are never duplicated. This example comes from the documentation:

.env
.env.local
config/secrets.json

This applies to every worktree Claude Code creates with git: --worktree sessions, subagent worktrees and parallel sessions in the desktop app. It doesn't apply if you replaced worktree creation with a WorktreeCreate hook. In that case, copy the files in your hook script.

Two things to plan for when several worktrees run at once:

• Shared local resources. The Claude Code docs don't cover this, but separate file trees don't give you separate ports, databases or Docker containers. If every worktree starts a dev server on the same port or migrates the same local database, the sessions will collide. Give each worktree its own port or database name, for example through its env file.
• Git LFS. If you set up LFS with git lfs install --local, worktrees that Claude Code creates contain LFS pointer files, not the real files. Claude Code skips filter drivers defined in the repository's own config when it creates a worktree, because a filter driver is a shell command that anything able to write to the repository could have planted. A plain git lfs install, which writes to your global config, isn't affected. To get the real files, run git lfs pull inside the worktree.

Isolate subagents with worktrees

Subagents that Claude spawns can each get their own worktree too, so their parallel edits don't conflict. Ask Claude to "use worktrees for your agents," or make it permanent for a custom subagent by adding isolation: worktree to its frontmatter:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

Put that file in .claude/agents/. Each run gets a temporary worktree, and Claude Code removes it automatically if the subagent finishes without changes. A worktree with changes stays on disk. A periodic sweep removes subagent and background-session worktrees once they are older than your cleanupPeriodDays setting, but it leaves any worktree that still has changed or untracked files or unpushed commits. Subagent worktrees use the same base-branch setting as --worktree. If subagents need to build on unpushed work, set worktree.baseRef to "head".

What Claude Code enforces inside a worktree

While a session is isolated in a worktree, Claude Code blocks some tool calls that would reach back into the main checkout. The same checks apply to subagents spawned from that session. The documentation lists four:

1. File edits: blocks an Edit, Write or NotebookEdit call that targets a path in the main checkout.
2. Command working directory: blocks a command whose working directory resolves to the main checkout, or whose working directory it can't confirm stays outside it.
3. Git redirects: blocks a command that points git at the main checkout through git -C, --git-dir, a GIT_DIR or GIT_WORK_TREE variable, or a cd into the main checkout before running git.
4. Command shape: blocks a command when Claude Code can't tell from its text that any git it runs stays inside the worktree. You can't turn this check off.

PowerShell commands get only the working-directory check. The documentation also spells out the limits: none of the checks tracks which files a shell command writes, so a cp or shell redirect into the main checkout isn't caught. Those commands fall under your normal permission and sandbox settings. Treat worktree isolation as protection against accidents, not as a security boundary.

Some things are shared on purpose. If you choose "Yes, and don't ask again" for a Bash command in a worktree session, the rule goes into the main checkout's .claude/settings.local.json. It then applies in the main checkout and in every other worktree of the repository, and it stays after the worktree is removed. On Windows, and in a few other cases the docs list, the rule stays with the worktree instead. Plugins installed at project scope from the main checkout also load in its worktrees.

Clean up worktrees

When you exit an interactive worktree session, Claude Code checks for anything removal would destroy: changed or untracked files, uncommitted work in checked-out submodules, and new commits.

• Clean worktree: for an unnamed session, Claude removes the worktree and its branch automatically. A named session asks first.
• Worktree with work in it: you choose whether to keep it or remove it. If you keep it, Claude Code prints a claude --worktree <name> --resume command so you can come back later. Removing it deletes the directory, the branch and all the work in them.
• State can't be verified: Claude Code asks you rather than removing it automatically.

Non-interactive runs (-p) have no exit prompt, so Claude doesn't clean up their worktrees. The lock Claude Code put on each one at creation also stays until a later session's sweep releases it. Remove these worktrees with git, unlocking first if git refuses because the worktree is locked:

git worktree list
git worktree unlock .claude/worktrees/feature-auth
git worktree remove .claude/worktrees/feature-auth

git worktree remove only removes clean worktrees, meaning no untracked files and no changes to tracked files. A worktree that isn't clean, or that contains submodules, needs --force, so check first that nothing in it matters. If you deleted a worktree directory by hand, git worktree prune removes the leftover administrative data. Add -n to see what it would remove without removing anything.

Manage worktrees manually

Use git directly when you need an existing branch or a location outside the repository:

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix fix-issue-456
cd ../project-feature-a
claude

The first command creates a new branch. The second checks out a branch that already exists. Claude Code's sweep never removes worktrees you created yourself with git worktree add, so cleaning those up is your job.

Merging parallel work back

Worktrees keep work apart, but they don't put it back together. Five sessions on five branches means five merges, and any conflicts the worktrees postponed show up then. Some habits that help:

• Split work by area, not by size. Two agents editing the same module will conflict however well their files are isolated.
• Merge often. Short-lived branches drift less from main.
• Run your full checks on the merged result, not only on each branch. Two branches can each pass alone and still break when combined.

Atlas, an AI engineering team built on Claude Code, handles this step for its own engineers. Each engineer works in its own copy of the code, so engineers never edit the same files under each other. Finished work goes to a landing train, which merges up to six finished branches, runs the project's own checks once on the combined result, and splits a failing batch until it finds the branch that broke it. Main's history is never rewritten. Each test run also gets its own copy of the project's database per worker, which covers part of the shared-database problem described above.

Checklist

1. Make at least one commit and add .claude/worktrees/ to .gitignore.
2. Write a .worktreeinclude for your env files.
3. Start each session with claude --worktree <name>.
4. Add isolation: worktree to subagents that edit files in parallel.
5. Give each worktree its own ports and databases.
6. Remove worktrees left by -p runs yourself.

For more on running a team of AI engineers, see the Atlas home page.