Enable hot-reload for SDK configuration by migrating from CLI args to settings files

[junhongwang418]

I just discovered something really cool in Claude Code v1.0.90 - the settings files now support hot-reload. Yesterday I was looking at the release notes and noticed this feature where you can edit ~/.claude/settings.json and Claude Code picks up the changes immediately without needing to restart anything. This is amazing for interactive mode.

But here's the thing - I'm working on an app that uses Claude Code in SDK mode, and I have to pass all the configuration through CLI arguments every time. Looking at my code in Shift/Utils/ClaudeCode.swift:L837, I'm building these massive command strings with --add-dir, --mcp-config, --allowedTools, and all sorts of other flags. Every time I want to change which directories are accessible or update the MCP server configuration, I have to restart my entire AgentRunner process.

This morning I realized we're missing out on a huge opportunity here. If SDK mode could read from the same settings files that interactive mode uses - ~/.claude/settings.json, .claude/settings.json, and .claude/settings.local.json - then we could get the same hot-reload benefits. Imagine being able to add a new directory to additionalDirectories in the settings file and having the SDK pick it up instantly without restarting the parent process.

The way I see it working is that SDK mode would check for these configuration files first, then CLI arguments could override specific settings if needed. This would be backward compatible - existing SDK integrations keep working with their CLI args, but new ones could leverage the file-based config for dynamic updates.

This connects to the broader vision of making Claude Code more adaptable in production environments. Right now, changing SDK configuration means killing processes, losing context, and disrupting user workflows. With hot-reload from settings files, we could adjust permissions, add new MCP servers, or modify allowed tools on the fly.

The implementation seems straightforward since the file watching and hot-reload logic already exists for interactive mode. We'd just need to extend it to SDK mode and ensure CLI args properly override file settings when both are present.

Success looks like:

• [ ] SDK mode reads configuration from ~/.claude/settings.json and project-level settings files
• [ ] Changes to settings files are picked up without restarting the SDK process
• [ ] CLI arguments override settings from files when both are specified
• [ ] Documentation updated to explain the configuration precedence
• [ ] The --add-dir directories can be managed via additionalDirectories in settings
• [ ] MCP server configuration can be updated through settings files instead of --mcp-config JSON

[coygeek]

This is a fantastic feature request. I completely agree that aligning the SDK's configuration behavior with the interactive mode would be a huge improvement for building robust, long-running agents.

I was dealing with a similar issue and did some digging. It looks like part of the puzzle is already there, which is great news!

I noticed in the CLI Reference documentation and the Python SDK's changelog (v0.0.18) that there's a --settings <file-or-json> flag.

For example, in the Python SDK, ClaudeCodeOptions has a settings parameter. This could solve the immediate problem of building those massive command strings you mentioned from Shift/Utils/ClaudeCode.swift:L837. Instead of passing dozens of flags, you could point the SDK to a single settings.json file on startup. The docs on settings.json also show an additionalDirectories key, which seems to map directly to --add-dir.

However, you've hit on the most critical part: this is likely a static load at startup. The real game-changer is the hot-reloading you're proposing.

Your idea of having the SDK process watch the settings.json files and dynamically update its configuration without a restart would be incredibly powerful. For any long-running agent, being able to:

• Update permissions on the fly.
• Add or remove MCP servers without killing the process.
• Tweak allowed tools for security or functionality reasons.

...all without losing the agent's current context, is a massive win.

+1 on this. Building on your success criteria, here’s how I see the ideal implementation:

• [x] The SDK honors the full settings hierarchy on startup (enterprise -> cli -> project.local -> project -> user). The --settings flag could fit in as a high-precedence file-based source.
• [ ] The SDK process actively watches the user and project-level settings.json files for changes.
• [ ] When a change is detected, the configuration is reloaded and applied to the current session dynamically. This includes permissions, additionalDirectories, and MCP configurations.
• [ ] CLI arguments provided at launch should always take precedence and remain static for the session's lifetime, overriding any conflicting settings from the reloaded files.
• [ ] The documentation is updated to clearly explain this new dynamic behavior and the precedence rules for the SDK.

This would make the SDK feel much more integrated and production-ready. Hope the dev team considers this

[cowwoc]

For what it's worth, I don't think that hot-reload of ~/.claude/settings.json actually works. For example, if you add/remove/update hook scripts in version 2.0.35 (the latest version as of the moment) then they will not take effect unless you restart claude.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.