Claude Code installer writes personal config to team-shared files; add --personal flag for gitignored variants

[steven-pribilinskiy]

Summary

The Claude Code installer (codegraph install -t claude -l local) writes three files into the project, and two of the three go to the team-shared variant when they should default to the personal/gitignored variant. This silently turns a personal install choice into a team mandate every time the user runs git add .claude/ after install.

Proposing a --personal flag (name TBD — --gitignored or --isolated also fine) that routes every write to the gitignored / personal-scope variant so the install leaves zero footprint in the team-tracked tree.

What the installer writes today (v0.8.0, -l local)

File written	Tracked by git?	Should be personal?
./.mcp.json (MCP entry)	✅ committed	Arguable — see below
./.claude/settings.json (permissions, if --auto-allow)	✅ committed	Yes — this is the bug
./.claude/CLAUDE.md (instructions)	✅ committed	Yes — this is the bug

-l local currently means "write to the project," but it conflates two orthogonal axes — project-scope vs user-scope and team-shared vs personal. Claude Code actually has three relevant scopes:

1. Global / user-scope: ~/.claude.json, ~/.claude/settings.json, ~/.claude/CLAUDE.md — every project sees it
2. Project-scope, team-shared: ./.mcp.json, ./.claude/settings.json, ./.claude/CLAUDE.md — committed
3. Project-scope, personal: ./.claude/settings.local.json, ./CLAUDE.local.md — gitignored by Claude Code's default scaffolding

The installer only models (1) vs (2). Option (3) is missing.

Why each write is wrong by default

1. Permissions in settings.json — personal trust, not team policy

--auto-allow is fundamentally a personal trust decision ("I personally trust the codegraph binary on my machine"), not a team policy ("everyone on this repo must auto-allow codegraph"). Yet by writing to settings.json it becomes the latter the moment someone runs git add .claude/settings.json.

Worse case (and what happened to me): the project's settings.json already contained legitimately shared hooks config from a teammate. The installer appended permissions into the same file, so the resulting diff co-mingles personal trust grants with team-shared hook config — un-tangling them later requires manual surgery.

Correct destination: ./.claude/settings.local.json. Claude Code's .gitignore scaffolding includes settings.local.json by default; it's exactly the file for this case.

2. Instructions in .claude/CLAUDE.md — committed shared memory

./.claude/CLAUDE.md is loaded into every Claude Code session at startup, costing ~720 tokens forever even for sessions that never query a symbol. That's an acceptable cost for the installing user, but it shouldn't get pushed onto every teammate's session budget — especially teammates who don't have codegraph installed and would have the section claim a codegraph_* MCP server exists when it doesn't.

Correct destination: ./CLAUDE.local.md (project-root, gitignored by default in Claude Code's scaffolding). Claude Code auto-loads it the same way as the shared CLAUDE.md, just for the local user.

(Separately, a .claude/skills/codegraph/SKILL.md would be even better for Claude Code specifically — skills are lazy-loaded only when the LLM decides they're relevant — but that's a deeper change. The CLAUDE.local.md move is the minimum fix.)

3. MCP entry in .mcp.json — borderline

.mcp.json is also committed by default. Argument for keeping it shared: it's a declaration, not a trust grant — Claude Code's enabledMcpjsonServers (in settings.local.json) lets each teammate opt in individually, so a committed .mcp.json entry doesn't auto-activate for teammates who don't add it to their personal opt-in list.

Argument for routing it to a personal variant under --personal: if only the installing user has the codegraph binary on PATH, the entry in .mcp.json is dead weight for everyone else, and the teammate-opt-in-via-enabledMcpjsonServers story isn't documented anywhere in this installer's flow.

A --personal flag could add codegraph to the user's personal enabledMcpjsonServers list in settings.local.json so the project-shared .mcp.json declaration only activates for them — net effect: declaration is in the repo (any teammate who installs codegraph just adds it to their enabledMcpjsonServers and they're set), but it doesn't activate by default for anyone else.

What --personal should do

codegraph install -t claude -l local --personal

Routes writes to:

Concern	Default (today)	--personal
MCP entry	.mcp.json	.mcp.json (unchanged — declaration only) + add codegraph to settings.local.json's enabledMcpjsonServers
Permissions (--auto-allow)	.claude/settings.json	.claude/settings.local.json
Instructions	.claude/CLAUDE.md	CLAUDE.local.md (project root)

And on codegraph uninstall --personal, reverse the same files. The current uninstall only knows about the shared paths, so a --personal install would also need a --personal uninstall to clean up correctly.

Why a flag instead of just changing the default

I'd argue --personal should be the default for -l local (and the current behavior should require an explicit --shared flag), because:

• Solo developer: no difference, files go to gitignored paths nobody else sees
• Team repo: doesn't silently mandate codegraph for everyone
• Open-source contributor: cloning the repo doesn't inherit upstream's install choices

But changing the default is a breaking change for anyone already shipping codegraph as team policy, so a flag is the safer first step.

Existing related issues

• Claude code current project only mcp json file #207 (closed) — .claude.json vs .mcp.json. Fixed in v0.8.0 for the MCP entry routing, but the fix didn't address that the permissions added by the same install are still going to the wrong file (settings.json instead of settings.local.json). The "scope-aware writes" lesson was applied to one of three writes, not all three.
• Wrong file for claude code? #215 (closed) — same .claude.json complaint.
• Support for multiple team members/main branch vs feature branch tracking #141 (open) — multi-developer tracking, different concern but adjacent (also about the team-vs-personal split).

Reproduction

Fresh project with an existing shared .claude/settings.json containing a team hook:

echo '{"hooks":{"PreToolUse":[{"matcher":"Write","hooks":[{"type":"command","command":"./hook.sh"}]}]}}' > .claude/settings.json
git add .claude/settings.json && git commit -m "team hook"

npx @colbymchenry/codegraph@latest
# (choose: claude, just-this-project, auto-allow yes)

git diff .claude/settings.json
# Shows codegraph permissions added INTO the team-shared file,
# now indistinguishable from the team's hook config in the same JSON document.

cat .claude/CLAUDE.md
# 34-line codegraph section, will be loaded into every session for every teammate
# the moment this file is committed.

Environment

• codegraph: 0.8.0
• Claude Code: latest
• OS: Linux (WSL2, Ubuntu)
• Node: 22.x

Happy to send a PR if there's interest in the --personal flag design above — would want to confirm the flag name and uninstall semantics first.

[steven-pribilinskiy]

Two corrections / additions after digging deeper into Claude Code's documented and actual behavior:

1. .mcp.local.json is NOT actually read by Claude Code — I was wrong above

My original comment claimed .mcp.local.json is supported at runtime as a gitignored override, citing anthropics/claude-code#41003 (closed, fixed v2.1.119). I tested this on Linux/WSL and it doesn't work: an MCP entry placed in .mcp.local.json produces zero loaded tools after a restart, while the same entry in .mcp.json loads fine. Either #41003 was Windows-specific behavior, the reporter was mistaken about the runtime merge, or the feature was reverted — the official docs at https://code.claude.com/docs/en/mcp never mentioned .mcp.local.json and I should have trusted that signal harder.

The honest Claude Code MCP scope model is:

Scope	Loads in	Shared with team	Stored in
user	All your projects	No	~/.claude.json (top-level mcpServers)
project	Current project only	Yes (via VCS)	.mcp.json in project root
local	Current project only	No	~/.claude.json under projects[<path>].mcpServers

There is no project-root personal-MCP file. For codegraph's --personal mode, the two real options are:

• Option A — .mcp.json + gitignore: Keep the installer's .mcp.json write but ensure the file is in the user's global gitignore (or the project's). Simple, works today, but turns off Claude Code's documented "share team MCP servers via VCS" feature for that file.
• Option B — ~/.claude.json projects[].mcpServers: True Claude Code "local scope" per the docs. This is what claude mcp add --scope local writes. Correct semantically, but requires safe edits to a large user-scope JSON file (lots of session state in there, risky).

I'd argue Option B is the right behavior for --personal, since it matches claude mcp add --scope local 1:1 and never touches the project tree at all. The installer can shell out to claude mcp add --scope local instead of writing JSON directly, which avoids the file-manipulation risk.

2. The flag names should match Claude Code's own scope vocabulary

The current -l global / -l local naming actively conflicts with Claude Code's documented terminology:

Claude Code's scope name	What it means	Where it's stored	Codegraph today
user	All your projects, personal	~/.claude.json (top-level)	-l global
project	Current project, team-shared (committed)	.mcp.json in project root	-l local ← misleading
local	Current project, personal (gitignored / never-committed)	~/.claude.json under projects[<path>].mcpServers	(missing)

The codegraph installer uses "local" to mean what Claude Code calls "project" — exactly the inversion you'd want to avoid. Any user who already understands Claude Code's claude mcp add --scope local mental model has to invert it when reading codegraph's --location local.

Suggested rename (combines with the --personal proposal in the issue body):

codegraph install --scope user      # was: -l global
codegraph install --scope project   # was: -l local (team-shared, current behavior)
codegraph install --scope local     # NEW (was: --personal in the original proposal)
                                    # Implementation: shells out to `claude mcp add --scope local`
                                    # plus writes permissions to settings.local.json and
                                    # instructions to CLAUDE.local.md at project root

Same three scopes, same names, same semantics as claude mcp add --scope X. For the other agent targets (Cursor, Codex, OpenCode) where the trichotomy doesn't apply, --scope local would fall back to --scope project with a notice, since none of them have an equivalent personal-project layer.

This collapses the two installer issues (the personal-vs-shared routing AND the flag-name confusion) into one coherent change.

[steven-pribilinskiy]

For anyone hitting these installer-routing issues today and wanting a stopgap until the upstream --scope local fix lands: I wrote a Claude Code skill that re-applies the personalization after every codegraph install / upgrade. Drops the codegraph permissions into .claude/settings.local.json, the instructions into CLAUDE.local.md at project root, ensures .mcp.json is gitignored, and confirms the project's MCP opt-in (enabledMcpjsonServers) lists codegraph. Idempotent, so it's safe to re-run after each upgrade.

Updated: an earlier version of this skill (and the comment above) recommended renaming .mcp.json → .mcp.local.json. Don't do that — Claude Code does NOT read .mcp.local.json (on Linux/WSL at least; verified on v2.1+); the rename produces zero loaded MCP tools. The corrected skill keeps .mcp.json in place and adds it to the gitignore instead. See my comment above for the full Claude Code scope model.

Save as ~/.claude/skills/codegraph-personalize/SKILL.md:

---
name: codegraph-personalize
description: Post-install cleanup for the codegraph (`@colbymchenry/codegraph`) installer. Auto-load whenever the user runs `codegraph install`, `npx @colbymchenry/codegraph`, upgrades codegraph, or notices codegraph has re-created team-shared config files (`.claude/CLAUDE.md`, `.mcp.json` outside of gitignore, or `mcp__codegraph__*` entries in `.claude/settings.json`). The installer writes personal config into committed files — this skill moves those writes into Claude Code's gitignored personal variants so the install leaves zero footprint on the team-tracked tree. Idempotent — safe to re-run after every install or upgrade.
allowed-tools: Read, Edit, Write, Bash
---

# Codegraph post-install personalization

## Why this skill exists

The `@colbymchenry/codegraph` installer (`codegraph install -t claude -l local`) writes three files into the project's **team-shared** Claude Code config:

| Installer writes | Destination this skill enforces |
|---|---|
| `.claude/settings.json` (permissions, when `--auto-allow`) | `.claude/settings.local.json` (personal, gitignored) |
| `.claude/CLAUDE.md` (instructions) | `CLAUDE.local.md` at project root (personal, gitignored) |
| `.mcp.json` (MCP server entry) | Keep `.mcp.json`, but ensure it's gitignored (global or project) |

This is tracked upstream as [colbymchenry/codegraph#243](https://github.com/colbymchenry/codegraph/issues/243). Until the installer ships a `--scope local` flag (Claude Code's term for personal-project MCP scope), this skill re-applies the personalization after every install.

### Claude Code MCP scope quick reference

| Scope | Loads in | Shared with team | Stored in |
|---|---|---|---|
| **user** | All your projects | No | `~/.claude.json` (top-level `mcpServers`) |
| **project** | Current project only | Yes (via VCS) | `.mcp.json` in project root |
| **local** | Current project only | No | `~/.claude.json` under `projects[<path>].mcpServers` |

Key fact: **`.mcp.local.json` is NOT a documented or actually-implemented Claude Code file.** A GitHub issue (anthropics/claude-code#41003) made it look real, but on Linux/WSL Claude Code does not read it. The honest options for codegraph MCP personalization are (a) `.mcp.json` + gitignore (what this skill does — simplest), or (b) `~/.claude.json` projects[<path>].mcpServers (true Claude Code "local scope" — more correct but harder to manipulate safely). This skill picks (a) because the codegraph installer already writes `.mcp.json` and editing the global `~/.claude.json` from a skill is risky.

## When to run

Auto-load when any of these triggers appear:
- The user just ran `codegraph install`, `npx @colbymchenry/codegraph`, or `npm install -g @colbymchenry/codegraph`
- The user mentions upgrading codegraph
- `.claude/CLAUDE.md` exists in the current project (the installer's footprint)
- `.mcp.json` exists at project root AND is NOT covered by any gitignore layer
- `.claude/settings.json` contains any `mcp__codegraph__*` entries in `permissions.allow`

If none of these are present, this skill has nothing to do — exit immediately.

## Steps

### 1. Move codegraph permissions out of the team-shared `settings.json`

For each entry in `.claude/settings.json`'s `permissions.allow` that starts with `mcp__codegraph__`:
- Remove it from `.claude/settings.json`
- Add it to `.claude/settings.local.json`'s `permissions.allow` (create the file/structure if missing; don't duplicate entries already present)
- If `.claude/settings.json`'s `permissions.allow` becomes empty, delete the `allow` key (and the `permissions` object if it becomes empty)

The canonical codegraph permission list (as of v0.8.0):

```
mcp__codegraph__codegraph_search
mcp__codegraph__codegraph_context
mcp__codegraph__codegraph_callers
mcp__codegraph__codegraph_callees
mcp__codegraph__codegraph_impact
mcp__codegraph__codegraph_node
mcp__codegraph__codegraph_status
```

**Leave any other `hooks` / `permissions` / arbitrary keys in `.claude/settings.json` alone** — they are genuinely team-shared and must stay committed.

### 2. Move the codegraph instructions out of the team-shared `.claude/CLAUDE.md`

The installer writes a marker-delimited block to `.claude/CLAUDE.md`:

```
<!-- CODEGRAPH_START -->
## CodeGraph
…
<!-- CODEGRAPH_END -->
```

Actions:
1. Read `.claude/CLAUDE.md`. If it contains `<!-- CODEGRAPH_START -->`, extract the entire block from `<!-- CODEGRAPH_START -->` through `<!-- CODEGRAPH_END -->` inclusive.
2. Write that block (verbatim, markers included so it stays self-identifying) to `<project-root>/CLAUDE.local.md`. If the file already exists, replace any existing marked codegraph block; otherwise append.
3. Remove the block from `.claude/CLAUDE.md`. If the file is now empty (or whitespace-only), delete it.

Claude Code reads `CLAUDE.local.md` at session start automatically — same load behavior as `CLAUDE.md`, just for the local user.

### 3. Ensure `.mcp.json` is gitignored — do NOT rename it

The installer writes `.mcp.json`, and Claude Code only loads MCP servers from `.mcp.json` (project scope) or `~/.claude.json` (user/local scope) — **not from `.mcp.local.json`**. Renaming to `.mcp.local.json` will silently break the install: the file will exist, look right, and load zero tools.

So keep `.mcp.json` exactly where the installer put it. The personalization is to make sure the file is **gitignored** so it doesn't get committed:

1. Check coverage with `git check-ignore -v .mcp.json`. If it prints a match line, this step is done.
2. If not covered, prefer adding to the **global** gitignore (`git config --global core.excludesfile`, typically `~/.gitignore_global`). One line: `.mcp.json`. This gives every project the same protection without polluting team `.gitignore` files.
3. If the user explicitly wants project-local coverage, add `.mcp.json` to the project `.gitignore`. Note that this turns off the documented Claude Code "share team MCP servers via VCS" feature for this project — only do it when the team has agreed `.mcp.json` is personal-only here.

If `.mcp.json` contains other servers besides codegraph (e.g. atlassian, context7), leave them in place — gitignoring the whole file protects them all the same way and they continue to load for you.

### 4. Verify the opt-in for project-scoped MCP servers

When `enableAllProjectMcpServers` is `false` (the safe default for `.claude/settings.local.json`), Claude Code requires each `.mcp.json` server to be explicitly opted in via `enabledMcpjsonServers`. Check `.claude/settings.local.json`:

- If `enableAllProjectMcpServers` is `true`: no further action.
- Otherwise: ensure `enabledMcpjsonServers` is an array containing `"codegraph"`. Create the key if missing; append if absent; don't duplicate.

Without this opt-in, codegraph appears in `.mcp.json` but no `mcp__codegraph__*` tools materialize after a Claude Code restart — and `/mcp` lists the server as disabled. **This is the single most common silent failure** and worth a hard check at the end.

### 5. Verify gitignore coverage for the other personal files

`CLAUDE.local.md` and `.claude/settings.local.json` must also be gitignored. Check three layers in this order; stop at the first one that already covers the file:

For `CLAUDE.local.md`:
1. Project `.gitignore` — `grep -F 'CLAUDE.local.md' .gitignore`
2. Project `.git/info/exclude`
3. Global gitignore: `git config --global core.excludesfile`

If none cover it, **append `CLAUDE.local.md` to the global gitignore** — gives every project this user works on the same coverage without polluting team `.gitignore` files.

For `.claude/settings.local.json`: Claude Code's default `.gitignore` scaffolding almost always includes `*.local.json` or `settings.local.json` already. Verify with `git check-ignore -v`; only add if missing.

### 6. Final verification

Run these checks; all must pass:

```bash
git check-ignore -v CLAUDE.local.md .mcp.json .claude/settings.local.json
# All three must show a match line

! grep -l 'mcp__codegraph__' .claude/settings.json 2>/dev/null
# settings.json must NOT contain any codegraph permissions

! test -f .claude/CLAUDE.md || ! grep -q '<!-- CODEGRAPH_START -->' .claude/CLAUDE.md
# .claude/CLAUDE.md either doesn't exist OR doesn't contain the codegraph block

jq -e '.enableAllProjectMcpServers == true or (.enabledMcpjsonServers // [] | index("codegraph"))' .claude/settings.local.json > /dev/null
# codegraph must be opted-in via enabledMcpjsonServers (or all-servers must be enabled)

jq -e '.mcpServers.codegraph' .mcp.json > /dev/null
# codegraph entry must still exist in .mcp.json (we did NOT rename)

git status --short | grep -E '\.(mcp\.json|claude/CLAUDE\.md|claude/settings\.json)$' && echo "WARN: unexpected tracked changes" || true
# Should produce no tracked changes from the personalization
```

If any check fails, surface it explicitly — don't claim success.

Finally: **the user must restart Claude Code** for the new MCP server config to take effect. Tell them this explicitly. `/mcp reconnect` may pick up `.mcp.json` edits without a restart, but ToolSearch and the deferred-tool registry only refresh on a full restart.

## What this skill does NOT touch

- `~/.claude.json` — global user-scope and local-scope MCP / settings. Out of scope; editing it from a skill is risky (huge file, lots of session state).
- `.claude/skills/` — codegraph doesn't write skills today.
- `.codegraph/` — the index directory. Leave it alone.
- Any non-codegraph keys in `.claude/settings.json`, `.mcp.json`, `.claude/CLAUDE.md`. Specifically: project hooks (`lint-ui-patterns.sh`-style PreToolUse hooks) and team-shared MCP servers (atlassian, context7, etc.) MUST stay in their original team-shared files.

## When the upstream fix lands

If `colbymchenry/codegraph` adds a `--scope local` (or similar) flag that writes the MCP entry to `~/.claude.json` under `projects[<path>].mcpServers` and writes permissions/instructions to the gitignored variants natively, this skill becomes obsolete — use the flag instead and `rm -rf ~/.claude/skills/codegraph-personalize`. Track the status of [issue #243](https://github.com/colbymchenry/codegraph/issues/243).