feat: add --settings flag for custom Claude settings path

[fdkubuntu]

• Add --settings CLI flag (--settings=path form also supported)
• Add CLAUDE_SETTINGS_PATH env var support
• Add loadCustomSettings() for reading/validating custom JSON settings
• Update mapCliOptionsToSDK() to merge custom settings over defaults
• Custom settings override: allowedTools, disallowedTools, skipPermissions, permissionMode, model
• Graceful error handling: missing file, invalid JSON, wrong type → warn + fallback
• Document in CLI help text and .env.example

Summary by CodeRabbit

Release Notes

New Features

• Added --settings CLI option to specify a custom Claude settings JSON file path
• Custom settings path is now displayed in the application's status output

Documentation

• Added documentation for the new CLAUDE_SETTINGS_PATH environment variable
• Updated help text to include the new --settings CLI flag option

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 410a4f30-4002-4830-a15d-00caa0ee2c47

📥 Commits

Reviewing files that changed from the base of the PR and between 1628868 and 11d25bb.

📒 Files selected for processing (4)

• .env.example
• server/claude-sdk.js
• server/cli.js
• server/constants/config.js

---

📝 Walkthrough

Walkthrough

The changes add support for custom Claude settings via a new CLAUDE_SETTINGS_PATH environment variable and --settings CLI flag. The SDK now loads settings from a JSON file and applies them to override defaults for permissions, tools, and model selection, with CLI flags taking precedence over environment-based settings.

Changes

Cohort / File(s)	Summary
Environment & Configuration .env.example, server/constants/config.js	Added documentation for and implemented CLAUDE_SETTINGS_PATH environment variable support, allowing users to specify a custom Claude settings JSON file path.
CLI Interface server/cli.js	Introduced --settings <path> CLI flag to set custom settings file path; updated status output and help text to document the new setting; adjusted environment variable display formatting.
SDK Integration server/claude-sdk.js	Implemented loadCustomSettings() helper to load and parse settings JSON files; updated queryClaudeSDK() to load custom settings from CLI flag or environment variable; modified mapCliOptionsToSDK() to merge custom settings with precedence rules for permission mode, allowed/disallowed tools, and model selection.

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI Handler
    participant Config as Config Module
    participant FileSystem as File System
    participant SDK as SDK Mapper

    User->>CLI: Provide --settings flag
    CLI->>Config: Set CLAUDE_SETTINGS_PATH env var
    CLI->>Config: Query CLAUDE_SETTINGS_PATH constant
    Config->>FileSystem: Read settings JSON file
    FileSystem->>SDK: Return parsed settings object
    SDK->>SDK: Merge custom settings with options<br/>(precedence: CLI flag > custom settings > defaults)
    SDK->>SDK: Apply permissionMode, tools, model overrides
    SDK->>SDK: Build final SDK options

Loading

Possibly related PRs

• Feature/cli commands #223: Introduces CLI and environment-variable plumbing that forms the foundation for this PR's configuration system.
• fix: detect Claude auth from settings env #527: Implements reading Claude's settings.json for authentication detection; this PR extends that pattern to apply custom settings for SDK configuration options.

Suggested reviewers

• viper151
• blackmammoth

Poem

🐰 A settings file hops into view,
With flags and vars both fresh and new,
Custom Claude configs take their place,
Precedence rules set the pace,
nuzzles Configuration with grace!

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main feature added: a --settings CLI flag for custom Claude settings paths, which aligns with the primary changes across all modified files.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}