Free guide
Claude Code's Shell Head Start: Why Your zshrc May Run Before You Say Yes
Claude Code 2.1.327 made the first shell command of a session faster with a head start: your shell's startup file may run before you approve that command, even if you then say no. Here's what that file does for Claude, why it's the slow part, and the one environment variable that turns the head start off.

The short version
- Your zshrc is your terminal's opening routine. Claude Code runs it once per session and hands your aliases, functions and shell options to every command.
- That warm-up can be slow: an older Claude Code changelog entry calls re-running the shell profile a multi-second stall.
- Since 2.1.327 the warm-up may start before you approve the first command, and it may run even if you say no. CLAUDE_CODE_DISABLE_SHELL_HEAD_START=1 turns that off.
How it actually works
Think of a coffee bar warming up
Before the first order, a coffee bar runs its opening routine: machine on, grinder dialed in. Your shell startup file is the same thing for your terminal. It sets your aliases, your functions, your PATH tweaks and whatever tools you load when a new terminal opens.
Claude Code runs the routine once and writes down the result
Each Bash command Claude runs is a separate process, so nothing carries over by itself. Anthropic's docs say that at session start Claude Code sources ~/.zshrc, ~/.bashrc or ~/.profile depending on your shell, captures the resulting aliases, functions and shell options, and applies them to every Bash command. Environment variables are different: an export in one command won't be there in the next.
Why that warm-up is the slow part
A startup file can do a lot: load version managers, plugins, completions, prompts. Claude Code's own changelog (2.1.274) describes re-running the shell profile as a multi-second stall on the next command. So the first command of a session used to wait on that routine.
What changed in 2.1.327: the head start
The 2.1.327 release (November 17, 2026) says it improved the speed of a session's first Bash command: shell startup files may now run before that command is approved, even if it's refused. The command Claude wants to run still waits for your yes. Only your own startup file may run early.
How to set it up
1.Check your version
The head start is in Claude Code 2.1.327 and later. Update if you're behind.
claude --version claude update2.Time your startup file
This opens an interactive shell, runs your startup file, and exits, so you see how long the warm-up takes on your machine. Use the bash line if bash is your shell.
time zsh -i -c exit time bash -i -c exit3.Read what's in it
Open your startup file and look for anything beyond aliases and settings: lines that start programs, call the network, or print secrets. Those are the lines that now may run before you approve a command.
cat ~/.zshrc # or: cat ~/.bashrc ~/.profile4.Turn the head start off if you want
Set the variable in the terminal you launch Claude Code from. With it set, Claude Code skips the head start; your startup file is still read for the session as usual.
export CLAUDE_CODE_DISABLE_SHELL_HEAD_START=1 claude5.Need variables in every command? Use CLAUDE_ENV_FILE
Exports don't carry from one Bash command to the next. Anthropic's docs say to point CLAUDE_ENV_FILE at a shell script before launching Claude Code; it runs before each Bash command in the same shell process. Activating a virtualenv or conda environment before you start Claude Code also works.
export CLAUDE_ENV_FILE=~/.claude/env.sh claude
The fine print
- The head start comes from one line in the 2.1.327 changelog. CLAUDE_CODE_DISABLE_SHELL_HEAD_START isn't on Anthropic's environment variables page yet.
- The changelog says your startup file may run early, not that it always does, and it covers the session's first Bash command only.
- Anthropic's docs list env as a settings.json key for environment variables. Whether this variable works from there isn't documented, and we haven't tested it; exporting it in your shell is the sure way.
- The changelog doesn't say whether the head start applies in claude -p runs, inside the sandbox, or on Windows with PowerShell.
- Claude Code supports bash and zsh for its Bash tool. Other shells such as fish are not supported.
FAQ
Does Claude Code run my command before I approve it?
No. Only your own shell startup file may run early. The command Claude proposes still waits for your approval.
Why is the first Bash command in Claude Code slow?
Claude Code runs your shell startup file once per session to pick up your aliases, functions and shell options. A heavy startup file can take seconds. Since 2.1.327 Claude Code may start that early, before you approve the first command, so it starts sooner.
How do I turn off the shell head start in Claude Code?
Set CLAUDE_CODE_DISABLE_SHELL_HEAD_START=1 in the shell you launch Claude Code from, for example export CLAUDE_CODE_DISABLE_SHELL_HEAD_START=1, then run claude.
Which startup files does Claude Code read?
Anthropic's docs say ~/.zshrc, ~/.bashrc or ~/.profile, depending on your shell. It keeps the resulting aliases, functions and shell options for every Bash command.
Why don't my exports carry over between Claude Code commands?
Each Bash command runs in a separate process, so an export in one command won't be there in the next. Use CLAUDE_ENV_FILE or a SessionStart hook to set variables for every command.
Sources
- Claude Code 2.1.327 release notes
- Claude Code changelog
- Tools reference: what persists between commands
- Claude Code environment variables
Facts checked 2026-11-18 against the Claude Code 2.1.327 release notes (published November 17, 2026), the Claude Code changelog (2.1.274 entry) and Anthropic's tools reference and environment variables docs.
Want help building with tools like this?
Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.
Join Shipping SkoolMore free guides
Chrome DevTools MCP: Let Your Coding Agent See the Page It Builds
Google's free, open-source way to give your coding agent a real Chrome window and the DevTools you already use. What it does, how it works, how to set it up, and the fine print.
GPT-6.2 Drops Its Reasoning When You Edit Old Messages: How to Keep It
Every reasoning item is now tied to the conversation before it. Edit that history and the API drops the reasoning that follows. Here's how it works and how to keep it.
Inkling 2 Mini: Run Thinking Machines' Looped AI Model on Your Mac
Thinking Machines' new open-weights model runs on a 32GB Mac with the wifi off. What it is, how the loop trick works, how to set it up, and the fine print.