Settings

Configure Claude Code’s behavior through the /config command, settings files, and environment variables.

The /config command

Run /config at any point in a session to open the interactive settings menu. From there you can view and change your preferences without editing files by hand.

Global config file

Claude Code stores your global settings in ~/.claude/settings.json (or the path set by CLAUDE_CONFIG_DIR). This file is shared across all your projects.

You can point Claude Code at a different config directory by setting CLAUDE_CONFIG_DIR before launching. All config files, including settings.json, will be read from that path instead.

A minimal settings.json looks like this:

{
  "model": "claude-sonnet-4-6",
  "env": {
    "MY_API_KEY": "abc123"
  }
}

Settings also load from three additional scopes in priority order: managed policy settings (highest), user settings, and project settings (lowest). User settings live at ~/.claude/settings.json. Project settings live at .claude/settings.json inside your project.

Project instructions (CLAUDE.md)

Place a CLAUDE.md file in your project root (or in .claude/) to give Claude persistent instructions for that project. Claude reads this file automatically at the start of every session.

Use CLAUDE.md to describe:

• Project architecture and conventions
• Coding standards you want enforced
• Commands to run tests or build
• Context about external dependencies

# My Project

This is a TypeScript monorepo. Always use `pnpm` for package management.

Run tests with: `pnpm test`
Build with: `pnpm build`

## Code style
- Use named exports only
- Prefer `async/await` over `.then()` chains

Key settings

model

Override the default model Claude Code uses.

{
  "model": "claude-sonnet-4-6"
}

env

Set environment variables that will be available in every Claude Code session. Useful for API keys and tool configuration.

{
  "env": {
    "NODE_ENV": "development",
    "DATABASE_URL": "postgres://localhost/mydb"
  }
}

permissions

Control which tools Claude can use and which require confirmation.

{
  "permissions": {
    "allow": ["Bash(git *)", "Read(**/*.ts)"],
    "deny": ["Bash(rm -rf *)"],
    "defaultMode": "default"
  }
}

hooks

Configure scripts that run before or after Claude’s actions. See the Hooks page for the full reference.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          { "type": "command", "command": "prettier --write $CLAUDE_TOOL_OUTPUT" }
        ]
      }
    ]
  }
}

cleanupPeriodDays

Number of days to retain chat transcripts. Defaults to 30. Set to 0 to disable session persistence entirely.

{
  "cleanupPeriodDays": 7
}

includeCoAuthoredBy

Whether to include Claude’s co-authored-by attribution in commits and pull requests. Defaults to true.

{
  "includeCoAuthoredBy": false
}

/theme command

Run /theme to open the theme picker. Claude Code ships with several color themes for the terminal UI.

/vim command

Run /vim to toggle vim-style key bindings in the input box. Your preference persists across sessions.

Environment variables

Claude Code respects several environment variables for configuration:

CLAUDE_CONFIG_DIR · string

Path to the directory where Claude Code stores all config files, including settings.json. Defaults to ~/.claude.

ANTHROPIC_API_KEY · string

Your Anthropic API key. Takes precedence over any key stored via OAuth login.

CLAUDE_CODE_SIMPLE · boolean

Set to 1 to run in bare mode — skips hooks, plugins, skill directory walks, and all keychain/credential reads. Useful for CI environments. Equivalent to the --bare CLI flag.

CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR · boolean

Set to 1 to reset the working directory to the project root after each shell command.

AWS_REGION · string

AWS region used when connecting through Amazon Bedrock. Falls back to AWS_DEFAULT_REGION, then us-east-1.

CLOUD_ML_REGION · string

Vertex AI region. Defaults to us-east5. Per-model overrides are also available (e.g. VERTEX_REGION_CLAUDE_SONNET_4_6).

Variables set in settings.json under the env key are injected into Claude Code’s process environment at startup. They behave identically to shell environment variables for the duration of the session.