Coexistence guide

Will ClaudeKit break my existing Claude Code setup?

Short answer: no, not by default. ClaudeKit installs into ./.claude/ for the current project, preserves existing project config, and selectively merges settings.json. The command to treat with care is ck init --fresh.

Will it touch my global config?

No, unless you add --global. Default kit content installs inside this project.

Will it overwrite my CLAUDE.md?

No on normal updates if it already exists. CLAUDE.md is treated as user config and skipped.

What about my custom skills?

They survive a normal install. --fresh can remove CK-tracked or legacy kit folders.

What if this project already has .claude/?

Normal ck init scans project-local .claude/ files, protects custom files, and merges .claude/settings.json.

Where does ClaudeKit live after install?

By default, ClaudeKit only installs into the project you are currently opening. It does not change the shared Claude Code settings on your machine.

✓ Recommended

Project install (default)

$ ck init

Lives in: ./.claude/ (this folder only)

✓ Writes kit files into ./.claude/ for this project
✓ Existing project CLAUDE.md and user config files are preserved
✓ Existing ./.claude/settings.json is selectively merged
✓ Your ~/.claude/ global setup stays untouched

Only when you ask

Global install (opt-in)

$ ck init --global

Lives in: ~/.claude/ (your home)

! Uses ~/.claude/ by default, or CLAUDE_CONFIG_DIR when set
! Global settings.json is selectively merged; existing CLAUDE.md is preserved
! Affects every project you open

How ClaudeKit avoids clobbering your setup

When you run ck init in a project that already has Claude Code config, ClaudeKit does not make you choose what to do with every file one by one. It protects important project config files, merges settings.json, and only asks for confirmation if other files may be overwritten.

★ Default

Protected user config

Existing .gitignore, .mcp.json, .ck.json, .ckignore, .repomixignore, and CLAUDE.md are preserved. Project-local .claude/ files that are not part of the kit are scanned and protected too.

Default behavior for normal ck init and updates.

Selective settings merge

settings.json merges hooks and MCP servers, deduplicates commands, and preserves user-only entries.

Skipped only when --force-overwrite-settings is active; --fresh enables that flag.

Overwrite confirmation

For other existing files, interactive mode lists conflicts and asks whether to continue.

--yes, CI, or non-interactive runs skip prompts; protected files and settings.json still follow their special rules, while other conflicts can be overwritten.

How ClaudeKit knows what it installed

ClaudeKit records installed files in metadata.json and tracks installed hooks/MCP servers separately. That metadata powers selective updates, uninstall, and --fresh analysis.

metadata.json + settings.json

ClaudeKit-tracked — refreshable

"hooks/session-init.cjs"

ownership: "ck"

User-owned — preserved

"your-custom-hook.sh"

preserved during settings merge

The command that deserves a backup

ck init --fresh is a full reset. With current metadata.json, it removes ClaudeKit-owned and ClaudeKit-modified files while preserving tracked user-created files. Without usable metadata, it falls back to removing these kit folders: commands/, agents/, skills/, rules/, hooks/. There is no automatic backup.

What can get removed

Legacy or metadata-less installs can lose everything in these folders. Current tracked installs remove CK-owned/modified files from them.

commands/ · agents/ · skills/ · rules/ · hooks/

The -y flag does not make --fresh safer; treat it as destructive until you have a backup.

Safe way to use `--fresh`

1

Back up first

Copy your .claude/ folder to a timestamped backup. Takes 2 seconds.
```
$ cp -r ./.claude "./.claude.bak.$(date +%s)"
```
2

Run --fresh aware

You now have a safety net, so any missing custom file can be restored manually.
```
$ ck init --fresh
```
3

Restore what you need

Copy your custom files back from the backup, one folder at a time.
```
$ cp -r ./.claude.bak.<timestamp>/skills/my-skill ./.claude/skills/
```

Only need to refresh kit content? Use ck init --yes. Use ck update -y when you want to update the CLI package; after that, ClaudeKit may refresh kit content for detected local/global installs and will skip it when content is already latest.

FAQ

Does ClaudeKit overwrite my CLAUDE.md?

Normal ck init preserves an existing CLAUDE.md because it is listed as user config. In global mode, a missing ~/.claude/CLAUDE.md can be copied; with --fresh, global CLAUDE.md can be replaced.

What happens to my custom commands and skills?

Standard ck init scans for custom .claude files and protects them. The exception is --fresh: it removes CK-owned/modified files, and legacy installs without metadata fall back to deleting the kit component directories.

Can I uninstall ClaudeKit?

Use ck uninstall. It supports --local, --global, --all, --dry-run, --yes, and preserves user-created or modified files by default. Use --force-overwrite only when you really want full removal.

How do I update ClaudeKit safely?

ck init --yes only refreshes kit content; it does not update the CLI package. ck update -y updates the CLI package first, then may refresh kit content for local/global installs when content is not already latest. Avoid --fresh for routine updates.