ccmix

Claude Code settings mixer — TUI/CLI tool for managing settings across scopes

🌏 日本語版 README はこちら

ccmix is a terminal tool for interactively browsing, comparing, and moving items between Claude Code settings files. Think of it as a DJ mixer for settings.json — pick items from one scope and move them to another.

Why ccmix?

Claude Code uses a 4-file settings hierarchy:

Scope	File	Git
User global	~/.claude/settings.json	—
User local	~/.claude/settings.local.json	—
Project	.claude/settings.json	✅ committed
Project local	.claude/settings.local.json	.gitignore

As settings grow, keeping items in the right scope becomes tedious. You might want to:

• Promote a project-local permission rule to shared project settings
• Copy a hook config from one project to your global defaults
• Clean up duplicate entries scattered across files
• See what differs between global and project settings

ccmix handles this interactively via TUI. A CLI mode supports scripting.

Features

Core Operations

• copy — Duplicate an item from one file to another (source unchanged)
• move — Move an item between files (removed from source)
• delete — Remove a selected item from a file
• diff — Side-by-side comparison of two settings files

Granularity

Operate at any level of the settings tree:

permissions                          <- top-level key (whole object)
├── allow                            <- nested key (whole array)
│   ├── "Bash(git add:*)"           <- individual array element
│   └── "Read(src/**)"
├── deny
│   └── "Bash(rm:*)"
└── defaultMode: "default"           <- scalar value

Safety

• Dry-run / preview — Review changes before writing to disk
• Duplicate detection — Warns when copying an item that already exists in the target
• Smart conflict resolution — Arrays merge (deduped); scalar overwrites require confirmation

TUI Mode (default)

Tab-based interface for switching between the 4 settings files. Select items in the tree, then choose an operation and target.

┌─ ccmix ──────────────────────────────────────────────────────────┐
│ [user] [user-local] [project] [project-local]                    │
├──────────────────────────────────────────────────────────────────┤
│ ▼ permissions                                                    │
│   ▼ allow                                                        │
│     ☑ Bash(git add:*)                                            │
│     ☐ Read(src/**)                                               │
│   ▶ deny                                                         │
│   • defaultMode: "default"                                       │
│ ▶ hooks                                                          │
│ • model: "claude-sonnet-4-20250514"                              │
│ ▶ env                                                            │
│                                                                  │
├──────────────────────────────────────────────────────────────────┤
│ [c]opy  [m]ove  [d]elete  di[f]f  │  target: [user-local ▾]     │
│ [p]review  [q]uit                  │  1 item selected             │
└──────────────────────────────────────────────────────────────────┘

CLI Mode

For scripting and CI/CD pipelines:

# Copy a permission rule from project to user global
ccmix copy --from project --to user --path "permissions.allow[0]"

# Move all hooks from user-local to project
ccmix move --from user-local --to project --path "hooks"

# Delete a specific deny rule
ccmix delete --from project --path "permissions.deny[0]"

# Show diff between user and project settings
ccmix diff --from user --to project

# Dry run (preview without writing)
ccmix copy --from project --to user --path "permissions.allow" --dry-run

Installation

brew install youyo/tap/ccmix

Or install with Go:

go install github.com/youyo/ccmix@latest

Pre-built binaries are also available on the Releases page.

Usage

# Launch TUI (loads project settings from current directory by default)
ccmix

# Launch TUI for a different project
ccmix --project /path/to/project

# CLI mode
ccmix <command> [flags]

ccmix auto-detects settings files relative to the current directory:

• User scope: ~/.claude/settings.json and ~/.claude/settings.local.json (always loaded)
• Project scope: .claude/settings.json and .claude/settings.local.json from the current directory (or --project path)

Commands

Command	Description
ccmix	Launch interactive TUI
ccmix copy	Copy an item between files
ccmix move	Move an item between files
ccmix delete	Delete an item from a file
ccmix diff	Compare two settings files
ccmix list	List all detected settings files and their contents
ccmix validate	Validate settings against JSON Schema

Flags

Flag	Description
--project, -p	Project directory path (default: current directory)
--from	Source scope: user, user-local, project, project-local
--to	Target scope
--path	JSON path to item (e.g. permissions.allow[2])
--dry-run	Preview changes without writing
--force	Overwrite scalar values without confirmation
--no-color	Disable color output

Conflict Resolution

When the same key already exists in the target:

Type	Behavior
Array (e.g. permissions.allow)	Merge with deduplication
Scalar (e.g. model)	Prompt for confirmation (--force to skip)
Object (e.g. hooks)	Deep merge (recursive)

Settings Schema

ccmix validates against the official Claude Code settings schema:

https://json.schemastore.org/claude-code-settings.json

Tech Stack

• Language: Go
• TUI: Bubble Tea + Lip Gloss + Bubbles
• CLI: Kong
• JSON: encoding/json + tidwall/gjson / tidwall/sjson path operations

License

MIT