Support custom path for ~/.claude.json

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Description
Claude currently uses ~/.claude.json as the default configuration file path. It would be very helpful to support a way for users to specify a custom path for this file instead of always relying on the fixed location in the home directory.

Problem
Using a hardcoded config path creates several limitations:

1. Poor environment isolation

Different projects, accounts, or environments may require different Claude configurations, but today they all have to share the same file.

1. Container / CI / remote environment friction

In Docker, CI pipelines, and remote development environments, the home directory may not be stable, appropriate, or easy to manage.

1. Enterprise security and compliance needs

Some teams need configuration files to live in controlled directories for permission management, auditing, backup, or mounted secret storage.

1. Harder migration and config management

Allowing the config file to live in a project-specific or user-defined location would make it easier to integrate with dotfiles, environment setup scripts, and versioned development workflows.

Proposed Solution

Requested solution
Please add support for overriding the config file path through one or both of the following:
• CLI flag
Example: claude --config /path/to/claude.json
• Environment variable
Example: CLAUDE_CONFIG=/path/to/claude.json

The current behavior should remain the default fallback when no custom path is provided.

Suggested precedence
A reasonable resolution order would be:

1. --config CLI flag
2. CLAUDE_CONFIG environment variable
3. Default path: ~/.claude.json

Example use cases
• Using different Claude configs for different projects
• Injecting a config path in CI
• Mounting config files in containers outside the home directory
• Managing team-wide config from a controlled directory

Expected benefits
• Better flexibility and portability
• Improved support for containers and automation workflows
• Easier configuration management for teams
• Reduced coupling to a specific filesystem layout

Acceptance criteria
• Users can specify the config file path via a CLI flag
• Users can specify the config file path via an environment variable
• If neither is provided, Claude continues to use ~/.claude.json
• Clear error messages are shown when the provided path does not exist or is not readable
• Documentation includes precedence rules and examples

Alternative Solutions

_No response_

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_