Claude Config Manager

Caution

THIS PROJECT IS HEAVILY OPINIONATED AND WORK-IN-PROGRESS

Before you use this, understand:

Folder Structure is STRICT - This app expects Claude Code configs in specific locations (see below). If your setup differs, it won't work correctly.
NOT Production Ready - This is alpha software. Bugs will happen. Always have your own backups.
Modifies Your Claude Configs - This app reads and writes to ~/.claude.json, ~/.claude/mcp.json, and your agents/skills folders. It creates backups, but understand the risk.
macOS-Focused Development - Primary testing on macOS. Windows/Linux support is theoretical until tested.

Use at your own risk. You've been warned.

What Is This?

An Electron desktop app to safely manage Claude Code configurations without risk of corrupting JSON files by hand.

The Problem:

Manually editing .claude.json is error-prone (one missing comma = broken config)
Too many MCPs loaded = bloated context tokens
No easy way to temporarily disable agents/skills without deleting them
Claude Code doesn't have a built-in config manager (yet)

The Solution:

Toggle MCPs, Agents, and Skills on/off with one click
Automatic backups before every change
"Archive" pattern: disabled items are moved, not deleted
Monaco-powered JSON editor for when you need raw access

Features

Feature	Status	Description
MCP Management	Done	Enable/disable MCP servers from `.claude.json` and `mcp.json`
Agent Management	Done	Toggle `.md` and `.json` agents in `~/.claude/agents/`
Skill Management	Done	Toggle skills (directories with `SKILL.md`)
JSON Editor	Done	Monaco editor with syntax highlighting
Backup System	Done	Auto-backup before every modification
Search	Done	Filter items by name
Token Estimation	Done	Rough token count display
Settings Tab	Planned	Configure app behavior
Import/Export	Planned	Share configurations

Screenshots

Agent Management

Toggle agents on/off, change models, search and filter

Built-in Editor

Monaco-powered editor with syntax highlighting

Requirements

Important

This app expects a SPECIFIC folder structure. If your Claude Code setup differs, the app will not find your configs.

Expected Directory Structure

~/ (your home directory)
├── .claude.json                 # Main Claude config (MCPs live here)
└── .claude/                     # Claude's data directory
    ├── mcp.json                 # Additional MCP configs (optional)
    ├── agents/                  # Your custom agents
    │   ├── my-agent.md          # Markdown agent
    │   └── another-agent.json   # JSON agent
    ├── skills/                  # Your custom skills
    │   └── my-skill/            # Skill directory
    │       └── SKILL.md         # Skill definition (required)
    └── .config-manager/         # Created by this app
        ├── backups/             # Automatic backups
        ├── mcp-disabled.json    # Disabled MCPs archive
        ├── agents-disabled/     # Disabled agents archive
        └── skills-disabled/     # Disabled skills archive

Path Resolution:

macOS: /Users/<username>/.claude/
Windows: C:\Users\<username>\.claude\
Linux: /home/<username>/.claude/

The app uses os.homedir() at runtime - no hardcoded paths.

Installation

From Source (Current Method)

# Clone the repository
git clone https://github.com/YOUR_USERNAME/claude-config-manager.git
cd claude-config-manager

# Install dependencies
npm install

# Run in development mode
npm run dev

Build for Distribution

# Build and package (creates DMG on macOS)
npm run package

# Output goes to ./release/

Pre-built Releases

Not available yet. Coming when the project is stable.

Usage

Starting the App

npm run dev

The app will:

Detect your home directory
Look for .claude.json and .claude/ folder
Load all MCPs, agents, and skills
Create .claude/.config-manager/ if it doesn't exist

Toggling Items

Click the toggle switch next to any MCP/Agent/Skill
Disable: Item is moved to the -disabled archive
Enable: Item is restored from the archive
A backup is created before every change

Editing JSON

Click the "Edit" button on any item
Monaco editor opens with the current config
Edit and save (changes are validated before writing)

Restoring Backups

Go to the Backups tab
Select a backup timestamp
Click "Restore" to revert to that state

After Making Changes

Warning

You must restart Claude Code for changes to take effect!

Claude Code reads configs at startup. After using this app, restart Claude Code or reload your IDE extension.

Architecture

Process Model

┌─────────────────────────────────────────────────────────────┐
│                    Electron Main Process                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   main.ts   │  │  preload.ts │  │  ipc-handlers.ts    │  │
│  │  (window)   │  │  (bridge)   │  │  (file operations)  │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└────────────────────────────┬────────────────────────────────┘
                             │ IPC (typed channels)
┌────────────────────────────▼────────────────────────────────┐
│                   React Renderer Process                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   App.tsx   │  │  MCPList    │  │  AgentList/SkillList│  │
│  │  (routing)  │  │  (toggle)   │  │  (management)       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Design Decisions

Archive Pattern: Disabled items are MOVED, not deleted. You can always restore them.
Atomic Writes: File writes go to .tmp first, then atomic rename. Prevents corruption on crash.
Backup First: Every modification triggers a backup BEFORE the change.
Context Isolation: Renderer process cannot access Node.js directly. All file ops go through IPC.
No External Network: The app never phones home. All operations are local.

Security

What the App Accesses

Path	Access	Purpose
`~/.claude.json`	Read/Write	Main MCP configuration
`~/.claude/mcp.json`	Read/Write	Additional MCP configs
`~/.claude/agents/`	Read/Write	Custom agents
`~/.claude/skills/`	Read/Write	Custom skills
`~/.claude/.config-manager/`	Read/Write	Backups and disabled item archives

What the App Does NOT Do

No network requests
No telemetry or analytics
No credential storage
No hardcoded paths (uses os.homedir())
No execution of MCP commands (just config management)

Electron Security

nodeIntegration: false
contextIsolation: true
Preload script with typed IPC bridge
No remote module

Project Structure

claude-config-manager/
├── electron/                  # Electron main process (Node.js)
│   ├── main.ts               # Window creation, app lifecycle
│   ├── preload.ts            # IPC bridge (contextBridge)
│   └── ipc-handlers.ts       # File operations, backup logic
│
├── src/                       # React renderer process
│   ├── main.tsx              # React entry point
│   ├── App.tsx               # Tab navigation, state management
│   ├── components/
│   │   ├── MCPList.tsx       # MCP toggle UI
│   │   ├── AgentList.tsx     # Agent management UI
│   │   ├── SkillList.tsx     # Skill management UI
│   │   ├── EditorModal.tsx   # Monaco JSON editor
│   │   └── ui/               # shadcn components
│   ├── lib/
│   │   └── utils.ts          # Formatting utilities
│   └── types/
│       └── electron.d.ts     # TypeScript definitions
│
├── dist-electron/            # Compiled Electron code
├── dist-renderer/            # Compiled React code
├── release/                  # Packaged app output
│
├── .claude/CLAUDE.md         # Project context for AI assistants
└── package.json              # Dependencies and scripts

Troubleshooting

"No configs found"

The app can't find .claude.json or .claude/ in your home directory.

Fix: Ensure Claude Code has been run at least once to create these files.

Changes don't appear in Claude Code

Claude Code reads configs at startup only.

Fix: Restart Claude Code or reload your IDE extension.

"Permission denied" errors

The app can't write to your .claude/ directory.

Fix: Check file permissions: ls -la ~/.claude/

Corrupted config after crash

Check the backups folder: ~/.claude/.config-manager/backups/

Each backup has a timestamp. Find the most recent good one and restore.

App shows wrong items

The app caches file state. If you edited files externally:

Fix: Restart the app to re-scan all configs.

Development

Scripts

npm run dev          # Start dev server + Electron
npm run build        # Build for production
npm run package      # Create distributable (DMG/EXE)

Tech Stack

Electron 39 - Desktop app framework
React 19 - UI framework
TypeScript 5 - Type safety
Vite 5 - Build tool
Tailwind CSS 3 - Styling
shadcn/ui - Component library
Monaco Editor - JSON editing

Adding Features

Add IPC handler in electron/ipc-handlers.ts
Expose in electron/preload.ts
Add types in src/types/electron.d.ts
Use in React components via window.electronAPI

Ask Claude to Help You Set This Up

Tip

Claude Code can help you install and configure this app!

Just tell Claude:

Help me set up Claude Config Manager from https://github.com/rotwurstesser/config-manager

Claude will:

Clone the repository
Install dependencies
Build and run the app
Help you understand your current configuration

This works because Claude Code can read the project's documentation and understands how to work with Electron apps.

Future Claude Sessions

Note

For Claude Code / AI assistants working on this project:

Quick Context

This is an Electron app for managing Claude Code configs. The codebase is well-structured:

electron/ = Node.js backend (file I/O)
src/ = React frontend (UI)
IPC bridge connects them via typed channels

Key Files to Read First

electron/ipc-handlers.ts - All file operations
src/App.tsx - Main component and state
src/types/electron.d.ts - IPC type definitions

Common Tasks

Add a new IPC channel:

Handler in ipc-handlers.ts
Expose in preload.ts
Type in electron.d.ts
Call via window.electronAPI.yourMethod()

Add a new UI component:

Create in src/components/
Use shadcn components from src/components/ui/
Style with Tailwind classes

Debug file operations:

All writes are atomic (.tmp → rename)
Backups happen BEFORE writes
Check .config-manager/backups/ for history

Known Issues / TODOs

Add unit tests for file operations
Test on Windows and Linux
Add Settings tab for app configuration
Add import/export for sharing configs
Add file watcher to detect external changes

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - do whatever you want, just don't blame me if it breaks.

Made for the Claude Code community

Because editing JSON by hand is so 2023

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
.claude		.claude
assets		assets
electron		electron
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.electron.json		tsconfig.electron.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation

Claude Config Manager

THIS PROJECT IS HEAVILY OPINIONATED AND WORK-IN-PROGRESS

What Is This?

Features

Screenshots

Agent Management

Built-in Editor

Requirements

Expected Directory Structure

Installation

From Source (Current Method)

Build for Distribution

Pre-built Releases

Usage

Starting the App

Toggling Items

Editing JSON

Restoring Backups

After Making Changes

Architecture

Process Model

Key Design Decisions

Security

What the App Accesses

What the App Does NOT Do

Electron Security

Project Structure

Troubleshooting

"No configs found"

Changes don't appear in Claude Code

"Permission denied" errors

Corrupted config after crash

App shows wrong items

Development

Scripts

Tech Stack

Adding Features

Ask Claude to Help You Set This Up

Future Claude Sessions

Quick Context

Key Files to Read First

Common Tasks

Known Issues / TODOs

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages