Allow customizing the .claude/ directory location

[Dwvil]

Preflight Checklist

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

Problem Statement

The .claude/ directory is currently hardcoded at the project root. Users cannot configure its location to match their preferred project structure or workflow.

Proposed Solution

Add a configuration option (e.g., in ~/.claude/settings.json or project-level settings.json) to specify a custom path for the .claude/ directory:

{
  "claudeDirectory": "/path/to/custom/.claude"
}

This would affect all contents currently stored under .claude/, including:

• worktrees/
• plans/
• agents/
• rules/

Alternative Solutions

No response

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

• Some users prefer to keep tool-specific working files (worktrees, plans, agents) in a custom location rather than the project root
• In monorepo or multi-project setups, users may want to consolidate Claude Code working directories elsewhere
• Personal preference for organizing dotfiles and tool directories

Additional Context

No response

[github-actions]

Found 3 possible duplicate issues:

1. [FEATURE] Feature request: CLAUDE_CONFIG_DIR environment variable to control .claude/ directory location #28808
2. Add environment variable to configure .claude config directory location #25762
3. Feature: Support per-instance config directory for multi-agent environments #15334

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[laniakea001]

This would be a valuable quality-of-life feature for power users and teams with specific directory organization preferences.

Potential Implementation Approaches:

1. Environment variable approach (simplest):

   This would be picked up at startup and override the default.

2. Settings.json configuration (your proposal):

   More explicit but requires changes to the config loading logic.

3. Hierarchical resolution (most flexible):

   • Check env var first
   • Then check
   • Fall back to in project root
   • This allows per-project, per-user, and global overrides

Use Cases This Enables:

• Monorepo consolidation: Single for multiple projects
• Symlink-friendly workflows: Store working files on faster drives
• CI/CD integration: Custom locations for ephemeral environments
• Team standardization: Organization-wide settings can point to shared directories

Considerations:

• Migration path for existing contents
• Path validation and creation of non-existent directories
• Compatibility with if it exists

This is a reasonable enhancement that wouldn't break existing workflows. 👍

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.