Skip to content

feat: Add hierarchical settings file support with Claude CLI compatibility #108

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: Add hierarchical settings file support with Claude CLI compatibility #108

wants to merge 3 commits into from

Conversation

kosukesaigusa
Copy link

@kosukesaigusa kosukesaigusa commented Jul 22, 2025 •
edited
Loading

Summary

This PR adds support for hierarchical settings files (.claude/settings.json) to claudecodeui, enabling persistent configuration management and compatibility with Claude CLI settings format.

Changes

  • ✅ Backend settings file management with Claude CLI format conversion
  • ✅ Unified settings React hook for centralized state management
  • ✅ API endpoints for settings CRUD operations
  • ✅ Enhanced UI showing currently applied rules
  • ✅ Intelligent merge strategies for different setting types
  • ✅ Comprehensive error handling and validation
  • ✅ Full JSDoc documentation

Benefits

  1. Persistent Configuration - Settings survive application restarts
  2. Claude CLI Compatibility - Seamlessly works with existing Claude CLI settings
  3. Project-specific Settings - Different configurations per project
  4. Team Collaboration - Share settings via version control
  5. Enhanced Security - Visual indication of permission settings

Screenshots

Manual Testing Performed

  • ✅ Tested with real ~/.claude/settings.json file
  • ✅ Verified Claude CLI format conversion works correctly
  • ✅ Confirmed settings hierarchy (project > global > defaults)
  • ✅ Tested UI updates reflect settings changes
  • ✅ Verified backwards compatibility with localStorage

Note: This codebase doesn't have a test suite yet. Following the existing pattern, this PR doesn't include automated tests. Happy to add them in a follow-up PR if desired.

Migration

No breaking changes. Existing localStorage settings are preserved and will be migrated to settings files on first save.

Closes #109

@kosukesaigusa
feat: Add hierarchical settings file support with Claude CLI compatib…
67e7948 
…ility

-
  Add support for ~/.claude/settings.json (global) and .claude/settings.json (project-specific)
  - Implement automatic conversion from Claude CLI format to claudecodeui format
  - Create unified settings management system with bidirectional sync
  - Add 'Currently Applied Rules' UI section showing active configuration
  - Support hierarchical settings with proper merge strategies
  - Add comprehensive error handling and validation
  - Include JSDoc documentation for all new functions
  - Maintain backwards compatibility with existing localStorage settings
@kosukesaigusa kosukesaigusa changed the title feat: Add hierarchical settings file support with Claude CLI compatib… feat: Add hierarchical settings file support with Claude CLI compatibility Jul 22, 2025
@kosukesaigusa kosukesaigusa mentioned this pull request Jul 22, 2025
Open
5 tasks
@viper151
Copy link
Contributor

viper151 commented Aug 6, 2025 •
edited
Loading

@kosukesaigusa sorry it took me some time to review this one. This is an amazing addition.

In some cases settings are not storred in .claude/settings but in ~/.claude.json
It might be legacy but I remember I had that issue in some of the dev servers where .claude/settings.json was not present.

In the backend, if I'm not mistaken I define that somewhere. Can you please check that and make sure it takes into account both of these files?

viper151
viper151 requested changes Aug 6, 2025
View reviewed changes
Copy link
Contributor

@viper151 viper151 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@kosukesaigusa sorry it took me some time to review this one. This is an amazing addition.

In some cases settings are not storred in .claude/settings but in ~/.claude.json
It might be legacy but I remember I had that issue in some of the dev servers where .claude/settings.json was not present.

In the backend, if I'm not mistaken I define that somewhere. Can you please check that and make sure it takes into account both of these files?

@viper151
Copy link
Contributor

@kosukesaigusa do you have any update on this one by any chance or shall I close this PR?

viper151
viper151 requested changes Aug 11, 2025
View reviewed changes
Copy link
Contributor

@viper151 viper151 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested in converation

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@viper151 viper151 viper151 requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Feature Request: Add support for persistent settings via .claude/settings.json files
2 participants
@kosukesaigusa @viper151