What does `claude -p --bare` skip at startup, and why do Claude Code's docs recommend it for scripts and CI?
answer
- same result on every machine
- no auto-discovery of anything
- hooks, skills, MCP, CLAUDE.md skipped
- API key, not subscription login
- 2.1.286 tightened the limits
basics
~20 s--bare skips auto-discovery of hooks, skills, custom commands, subagents, plugins, MCP servers, auto memory and CLAUDE.md, so a scripted run starts faster, behaves the same on every machine and runs no repository config it was not handed.
solid answer
~40 sWithout `--bare`, `claude -p` loads everything an interactive session would, from the working directory and `~/.claude`, and since `-p` shows no workspace trust dialog it runs a project's `.claude/settings.json` hooks and connects its `.mcp.json` servers even in a folder nobody trusted. `--bare` skips that auto-discovery: hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory and CLAUDE.md. Claude keeps Bash, file read and file edit, and you pass anything else explicitly with `--append-system-prompt`, `--settings`, `--mcp-config`, `--agents` or `--plugin-dir`. It never reads OAuth credentials or the keychain, so set `ANTHROPIC_API_KEY` or an `apiKeyHelper` in `--settings`. Since 2.1.286 it also connects only command-line MCP servers, sends no system reminders and starts no background tasks. It pre-approves nothing: tools still need `--allowedTools` or a `--permission-mode`.
code
bash · 6 linesexport ANTHROPIC_API_KEY="$CI_ANTHROPIC_KEY"
claude --bare -p "Summarize the failures in lint.log by rule" \
--append-system-prompt-file ./ci/triage-rules.md \
--mcp-config ./ci/mcp.json \
--allowedTools "Read" \
--output-format jsongo deeper
Recall that --bare makes claude -p skip hooks, skills, plugins, MCP servers, auto memory and CLAUDE.md, and that it needs an API key rather than a subscription login.
Explain how to hand a bare run its context explicitly with --settings, --mcp-config, --agents and the system prompt flags, and why that makes results reproducible.
Show why a -p run without --bare in an untrusted checkout runs its hooks and .mcp.json servers, and what the 2.1.286 limits on reminders and background tasks change.
Decide whether every pipeline must use --bare with config from the pipeline repository, trading convenience of developer settings for reproducibility and a smaller attack surface.
## What a normal `-p` run loads `claude -p` is not a stripped-down client. Without extra flags it builds the same **context** an interactive session would: it discovers configuration in the working directory and in the user's `~/.claude` folder and loads all of it. That includes: - **Hooks** from settings files, which run shell commands on events. - **Skills, custom commands and subagents** from `.claude/` folders. - **Installed plugins**. - **MCP servers**, including those in the project's `.mcp.json`. - **Auto memory** and **CLAUDE.md** instruction files. Two consequences follow for automation. First, the result depends on the machine: a hook in a teammate's `~/.claude` or a server in one checkout's `.mcp.json` changes what the run does. Second, `claude -p` shows **no workspace trust dialog** and no per-server approval prompt, so in a repository you have never trusted it still runs the project's hooks and connects its `.mcp.json` servers. Which repository content runs before trust is covered in depth by the material on workspace trust; for scripting, the remedy is one flag. ## What `--bare` skips `--bare` (minimal mode) turns auto-discovery off. Claude Code skips hooks, skills, custom commands, subagents, installed plugins, MCP servers, auto memory and CLAUDE.md, so the run **starts faster** and **does the same thing on every machine**. Claude keeps the Bash, file read and file edit tools. The flag also sets the `CLAUDE_CODE_SIMPLE` environment variable. One partial exception: a directory passed with `--add-dir` still contributes the skills in its `.claude/skills/` folder, while its `.claude/commands/` and `.claude/agents/` folders are skipped. ## Supplying context explicitly Bare mode does not forbid configuration; it requires you to name it. | To load | Pass | | --- | --- | | System prompt additions | `--append-system-prompt`, `--append-system-prompt-file` | | Settings | `--settings <file-or-json>` | | MCP servers | `--mcp-config <file-or-json>` | | Custom subagents | `--agents <file-or-json>` | | A plugin | `--plugin-dir <path>`, `--plugin-url <url>` | That turns the job's configuration into something checked into the pipeline next to the command, reviewed like code, rather than whatever happens to sit on the runner. ## Authentication changes In bare mode Claude Code **never reads OAuth credentials or the system keychain**, so a subscription login does not carry over. For the Anthropic API, set `ANTHROPIC_API_KEY` with a key from the Claude Console, or supply an `apiKeyHelper` in the `--settings` JSON. Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry keep reading their own provider credentials. A job that worked with a developer's login and fails after adding `--bare` usually needs exactly this. ## Runtime limits, tightened in 2.1.286 Bare mode also limits what happens while the run goes on: 1. **MCP servers**: only those supplied on the command line, for example with `--mcp-config`, connect. 2. **System reminders**: Claude gets the prompts and tool results without the reminders Claude Code would add, so it is not told when a file it read changes on disk and does not get the list of available skills. 3. **Background tasks**: none run; a shell command that reaches its timeout stops instead of moving to the background. Before 2.1.286 these held only partly: an interactive `--bare` session connected the usual MCP servers, every `--bare` session sent system reminders, and background tasks stayed available. ## What `--bare` does not do - **It does not pre-approve anything.** Tools still need `--allowedTools` entries or a `--permission-mode`; the docs' own example pairs `--bare` with `--allowedTools "Read"`. - **It is not `--safe-mode`.** Safe mode is for troubleshooting a broken configuration and keeps the normal login and model selection; bare mode is for reproducible scripted runs. - **It is not yet the default.** The docs recommend it for scripted and SDK calls and say it will become the default for `-p` in a future release, so add it explicitly today. ## When to reach for it Use `--bare` whenever the run's behaviour should be decided by the pipeline rather than by the machine or the checkout: - **CI jobs**, where runners differ and nobody inspects their `~/.claude`. - **Jobs over repositories you did not write**, such as a bot that triages pull requests from forks, where a project's hooks or `.mcp.json` should never run. - **High-volume scripted calls**, where skipping discovery shortens startup. Leave it off only when the job genuinely depends on the project's own configuration, and then say so explicitly in the pipeline, because that job also inherits whatever a contributor adds to that configuration later.
- A CI job fails to authenticate right after `--bare` is added; what changed?Bare mode never reads OAuth credentials or the system keychain, so the subscription login the job was relying on is gone. Set `ANTHROPIC_API_KEY` from the Claude Console or pass an `apiKeyHelper` in `--settings`; Bedrock, Google Cloud's Agent Platform and Microsoft Foundry keep using their own credentials.
- How do you give a `--bare` run one MCP server and a team prompt without re-enabling discovery?Name them explicitly: `--mcp-config ./ci/mcp.json` for the server and `--append-system-prompt-file ./ci/rules.md` for the instructions. Since 2.1.286 only servers supplied on the command line connect in bare mode, so the run uses exactly what the pipeline passes.
- --bare locks down permissions, so --allowedTools is unnecessary
- claude -p shows the trust dialog before running a repository's hooks
- --bare is just another name for --safe-mode
- --bare keeps using the claude.ai subscription login
- --bare is already the default for every claude -p run
Assumes Claude Code 2.1.286, the release where --bare began connecting only command-line MCP servers, sending no system reminders and starting no background tasks.