Bare Mode and Directory Expansion

--bare strips Claude Code down to its minimal boot path — no MCP auto-discovery, no automatic system prompt loading. Startup goes from several seconds to near-instant. --add-dir expands Claude’s working context to include additional repositories or directories beyond the current one. Together they give you precise, surgical control over what Claude Code loads and sees.

`--bare`: Skip Auto-Discovery

By default, Claude Code does several things on startup:

Scans for MCP servers configured in ~/.claude/config.json and project config, connects to each, and fetches their tool lists
Loads CLAUDE.md from the project root and parent directories
Reads memory files from ~/.claude/memory/
Loads any project-level instructions and context

This takes time. On a machine with several MCP servers configured, startup can take 3–8 seconds. For interactive sessions that is acceptable. For SDK usage, scripting, or tight latency loops, it is not.

--bare skips all of it:

# Standard startup (auto-discovery enabled)
claude "run the test suite"
# → 4.2s to first response token

# Bare startup (no auto-discovery)
claude --bare "run the test suite"
# → 0.4s to first response token

10x faster. The tradeoff: no tools, no memory, no project context unless you provide them explicitly.

Pairing `--bare` with Explicit Flags

When running bare, you opt in to exactly the context and tools you need:

# Bare + explicit system prompt
claude --bare --system-prompt "You are a code reviewer. Be concise." "review this diff: ..."

# Bare + specific MCP config (only the tools you need)
claude --bare --mcp-config ./my-tools.json "fetch the PR and summarize it"

# Bare + system prompt from file
claude --bare --system-prompt-file ./prompts/reviewer.txt "review src/auth.ts"

The --mcp-config flag accepts a path to a JSON file with the same format as the MCPs section of ~/.claude/config.json. You define exactly which servers to load — no others are connected.

// my-tools.json — minimal MCP config for a specific task
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

When to Use `--bare`

SDK Usage

When calling Claude Code programmatically from a script or application, you control the context explicitly. Auto-discovery adds overhead and may load tools that interfere with the scripted task.

#!/bin/bash
# CI script — bare for speed and determinism
claude --bare \
  --system-prompt "You are a CI analyzer. Output JSON only." \
  --mcp-config ./ci-tools.json \
  "analyze the test results in ./test-output/ and return a JSON summary"

Scripting and Pipelines

Chaining Claude Code into shell pipelines benefits from fast startup and predictable behavior:

# Pipeline: git diff → Claude analysis → GitHub comment
git diff HEAD~1 | claude --bare \
  --system-prompt "Summarize this diff in 3 bullet points. Be brief." \
  --print \
  | gh pr comment $PR_NUMBER --body-file -

Tight Latency Requirements

Any context where the user or calling system is waiting on Claude Code’s first response — interactive CLIs, IDE integrations, autocomplete-style tools — benefits from bare’s reduced startup time.

Boris’s Workflow

Boris Cherny uses --bare in SDK integrations to get 10x startup speed when Claude Code is invoked programmatically. His pattern: bare for any invocation that happens more than a few times per minute, full auto-discovery for interactive sessions.

`--add-dir`: Expand Working Context

By default, Claude Code works within the current directory. --add-dir adds another directory to Claude’s context — it can read files, write files, and run tools against both locations simultaneously.

# Add a second repository to the working context
claude --add-dir ../shared-lib "update the API client in shared-lib to match the new interface in src/"

# Add multiple directories
claude --add-dir ../shared-lib --add-dir ../design-tokens "refactor components to use the new design tokens from design-tokens/ and update shared-lib accordingly"

Multiple --add-dir flags stack. Claude Code sees all specified directories as part of its working context.

In-Session: `/add-dir`

If you are already in a Claude Code session and realize you need context from another directory, use /add-dir without restarting:

# Already in a session, realize you need the shared library
/add-dir ../shared-lib

# Claude Code confirms:
# → Added /Users/you/shared-lib to working context
# → 847 files indexed

# Now continue your task with access to both repos
"Now that you can see shared-lib, update the type definitions there to match what we just changed in src/"

Use Case: Cross-Repo Refactoring

The canonical use case for --add-dir is work that spans multiple repositories — changing an interface in a library and updating all consumers simultaneously.

# Working in a monorepo consumer, need to also edit the library
claude --add-dir ~/code/my-design-system \
  "the Button component's onClick type changed from React.MouseEvent to a custom ButtonClickEvent. Update the design system's Button component and every consumer of it in this repo."

Without --add-dir, Claude would only see the current repo and could not read or write the design system. With --add-dir, both are in scope.

Combining `--bare` and `--add-dir`

For scripted multi-repo tasks, combine both flags:

claude --bare \
  --add-dir ../packages/core \
  --add-dir ../packages/utils \
  --system-prompt "You are a migration assistant. Apply the changes exactly as described." \
  "migrate all usages of the old logger from packages/utils to the new one in packages/core"

Fast startup, multi-repo scope, explicit system prompt — no auto-discovery overhead, no unintended tool loading.

What Auto-Discovery Normally Does (That You Lose with `--bare`)

Understanding what --bare skips helps you know what to add back explicitly:

Auto-discovery feature	What it provides	How to replace in bare mode
MCP server loading	Tools (GitHub, filesystem, DB, etc.)	`--mcp-config <file>`
Project CLAUDE.md	Project instructions and context	`--system-prompt-file <path>`
Global memory files	Persistent facts across sessions	`--system-prompt` with relevant facts
Parent directory CLAUDE.md	Monorepo-level instructions	`--system-prompt-file <path>`

If you find yourself re-specifying the same --bare flags repeatedly, consider creating a shell alias or wrapper script:

# ~/.bashrc or ~/.zshrc
alias claude-ci='claude --bare --mcp-config ~/.claude/ci-tools.json --system-prompt-file ~/.claude/prompts/ci.txt'

Gotchas

No memory persistence. Bare sessions do not load or write memory files. Facts you want Claude to remember across bare sessions must be injected via --system-prompt each time.

No CLAUDE.md. Project instructions in CLAUDE.md are not loaded in bare mode. If your task depends on project context (architecture rules, style conventions), inject them via --system-prompt-file.

--add-dir paths are relative to CWD. If you are scripting from a different working directory than expected, use absolute paths:

claude --add-dir /absolute/path/to/shared-lib "..."

File permission boundaries. --add-dir adds read/write access to the specified directory. Claude Code respects the same permission model as normal — it will not write outside permitted paths. But be intentional about what you add: more directories mean more surface area.

Context Management

Bare Mode and Directory Expansion

--bare: Skip Auto-Discovery

Pairing --bare with Explicit Flags

When to Use --bare