settings.local.json — support host/OS-specific overrides for shared filesystem workspaces

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

When a project directory lives on a shared filesystem (NFS, SMB, etc.) and is accessed simultaneously from multiple machines running different operating systems, settings.local.json becomes a conflict point. The file is static JSON with no include or override mechanism, so whichever machine last wrote it wins — breaking the other machines' approved permissions.

This is an increasingly common setup: a NAS-hosted repo accessed from a Linux workstation, a Windows desktop, and a macOS laptop, all running Claude Code against the same source tree.

A further edge case: a dual-boot machine (e.g. Alma 8 and Alma 9 on the same host) shares the same hostname but requires different approved paths and commands per OS. A simple family tag is insufficient — is needed to distinguish them. More broadly, any user-defined environment variable should be usable in the include path, allowing arbitrary specificity. For example, if $CLAUDE_DEVICE is set, Claude Code would resolve the include as settings.${HOSTNAME}-${CLAUDE_DEVICE}.json — enabling distinctions like boot environment, role, or any other dimension the user chooses to express through their shell environment.

Currently, all permission approvals write to settings.local.json regardless of whether the command is machine-specific (e.g. a Windows path) or genuinely portable. There is no way to scope an approval at the point of prompt.

Proposed Solution

1. Settings hierarchy with host/OS-version resolution

Support a hostname/OS-version-based settings override chain, resolved at session startup:

1. .claude/settings.local.json — baseline shared project permissions (safe on all platforms)
2. .claude/settings.<hostname>.json — host-specific overrides, loaded if present
3. .claude/settings.<hostname>-<os-version>.json — most specific, loaded if present

Examples:
settings.nutball1-win11.json
settings.nutball1-alma9.json
settings.penny-alma9.json
settings.macbook-macos15.json

All machine-specific files gitignored by default. Claude Code merges them at session startup, most-specific wins on conflicts.

1. Explicit include with environment variable expansion

Rather than implicit filename probing, settings.local.json could alternatively support an explicit include directive with environment variable expansion resolved at startup:

{ "include": "settings.${HOSTNAME}-${OS_VERSION}.json", "permissions": { "allow": [] } }

Claude Code would: (1) read settings.local.json, (2) expand any env vars in include paths using the current environment, (3) load and merge the resolved file if it exists, with the included file's permissions taking precedence.
HOSTNAME is standard on Linux/macOS. Claude Code would need to provide OS_VERSION (or similar) as a well-known variable since there is no cross-platform standard for OS version in environment variables.
This approach mirrors patterns already familiar from shell configs, Docker Compose, and .env files, and gives the user explicit control over the merge rather than relying on implicit naming conventions.

1. Scoped permission prompts

The current permission prompt offers approve/deny. With a settings hierarchy in place, the prompt should expose scope explicitly:

claude wants to run: cmake --build build-linux

• Run once — execute now, don't remember
• Permit on this system — execute and write to settings.<hostname>-<os-version>.json
• Permit for this project — execute and write to settings.local.json (all machines)
• Don't run — deny

This gives users precise control over where a permission lands without requiring manual editing of settings files after the fact. It also eliminates the current problem where approvals always write to settings.local.json regardless of whether the command is inherently machine-specific or genuinely portable.

Alternative Solutions

• Storing machine-specific permissions in ~/.claude/settings.json (global) — works, but approved permissions during a session write to settings.local.json, requiring manual migration after every new approval
• Maintaining per-machine copies outside the repo — works, but loses the convenience of having settings versioned alongside the project

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

Any individual or team using a shared/network filesystem as the canonical project location, or anyone dual-booting where the same hostname runs multiple OS versions. Becomes more relevant as Claude Code adoption grows across heterogeneous environments.

Additional Context

_No response_