claude-switch-models-setup

Claude Code Profiles and Local Skill Activation

Overview

This skill creates an isolated-but-shared profile system for Claude Code CLI. Each profile gets its own .claude.json state file (provider credentials and session history) while sharing skills, projects, hook scripts, agents, and installed plugin state across all profiles — and converging each profile's settings.json (hook registration, marketplaces, env feature flags, permissions, preferences) plus the behavior slice of its .claude.json (e.g. workflowSizeGuideline) from the default profile, so the only intended difference between profiles is the model/provider.

The result: you can open one terminal with Kimi, another with DeepSeek, another with Anthropic — each running as a fully independent Claude Code process, without configuration bleed.

For reducing fixed startup context from preloaded MCP tool schemas, read references/mcp-startup-context.md. It owns same-mode measurement, active-profile discovery, provider compatibility checks, reversible server suppression, and fresh-process acceptance.

How It Works

• CLAUDE_CONFIG_DIR tells Claude Code CLI which directory to use as its config root.
• Each profile lives in ~/.claude-profiles/<name>/ with an isolated .claude.json.
• Content directories (skills/, projects/, hooks/, agents/, settings/) are symlinked back to the main ~/.claude/ directory so you only maintain one copy. Note this shares hook scripts, not hook registration — registration lives in each profile's own settings.json (next bullet).
• Config layer — settings.json: each profile has its own settings.json (Claude Code treats it as config-dir-local), so everything stored there — hook registration, extraKnownMarketplaces, enabledPlugins, env feature flags, permissions, behavior preferences — silently drifts the moment it changes in the default profile (measured 2026-07-18: 9/9 real profiles had zero hook registrations). sync-profile-settings.py is the converger: registered as a SessionStart hook, it copies every key from the default profile's settings.json into every profile's, except identity keys (top-level model and advisorModel — the latter is Anthropic-model routing a third-party endpoint can't serve; and env vars that carry provider routing or Anthropic-native isolation — ANTHROPIC_*, CLAUDE_CODE_SUBAGENT_MODEL, ENABLE_TOOL_SEARCH, DISABLE_GROWTHBOOK/TELEMETRY/AUTOUPDATER — which the provider settings file deliberately sets differently). Within env, convergence is two-way for non-identity keys: main's keys overwrite the profile's, and a non-identity key main no longer carries is deleted from the profile and reported (identity keys are exempt — main never carries them, so their absence is not deletion evidence). Profile-only top-level keys are preserved; nested collections inside a key main also has (e.g. permissions.allow, enabledPlugins) converge wholesale to main's value, and any profile-only nested entries dropped that way are listed (count on write, detail under --check) so the loss is visible rather than silent. This is what makes "everything except the model works in every profile" actually hold.
  • Scope is every profile, in every invocation. No argument-free, --all, or --check run ever covers a subset: all of ~/.claude-profiles/* plus $CLAUDE_CONFIG_DIR, every time. A run prints one line per profile it actually changed and nothing when there is no drift — so drift shows up in the session-start output instead of hiding, and a silent session start means converged. A $CLAUDE_CONFIG_DIR that is unset, empty, or not a profile directory is skipped, never created.
  • Exit codes: the argument-free run exits 0 unconditionally — it is a session-start hook and never blocks a session, including when a main file is corrupt (it warns, converges nothing, and exits 0, because a corrupt main reads as empty and converging toward empty would strip hooks from every profile). --check exits 1 on drift and 2 on a corrupt main file or a profile it could not read; --all writes and exits 2 on those same two failures — the difference between them is that --check writes nothing, not which failures return 2. --check --all is the same audit as --check. One unreadable profile is reported and skipped — it never cancels convergence for the others.
• State layer — .claude.json behavior keys: settings.json is not the only per-profile config file. Claude Code also keeps a per-profile state file (the main profile's is ~/.claude.json; each third-party profile's is <profile>/.claude.json — asymmetric paths, verified on disk), and a few behavior settings live only there (workflowSizeGuideline, notification/UI preferences). On 2026-08-17 workflowSizeGuideline: small existed only on the main profile and 10/11 third-party profiles had no copy — a Kimi session fanned one Dynamic Workflow out to 30+ agents with no size guidance in its system prompt. The same converger therefore also syncs an allowlist of behavior keys into each profile's .claude.json. The safety mechanism is a three-way classifier in the script, not a hand-maintained key list: allowlisted behavior keys sync; state/cache/counter/migration/credential keys (matched by name patterns) are never touched; anything unknown-and-different is reported — one line per drifted key per run, until a human classifies it (the tripwire that surfaces the next behavior key the day it appears). Writes are backup + atomic-replace; measured safe against a live harness rewriting the file (a marker key survived 30+ minutes of an active session). Applies next session — the harness reads this file at startup.
• Exception — plugins/: marketplace content and install state are shared, but each profile keeps its own known_marketplaces.json. Claude validates a marketplace's installLocation with path.resolve() (which does NOT resolve symlinks), so a single shared file would make every non-writing profile report "corrupted installLocation". claude-plugins-sync.py builds and maintains this per-profile structure.
• claude-plugins-sync.py also mirrors enabledPlugins from the default ~/.claude/settings.json into each profile's settings.json (sharing cache files is not enough; Claude Code treats "enabled" state as config-dir-local). It runs at profile launch and reactively — the LaunchAgent in the next bullet re-runs it on every write to the default profile's settings.json, so claude plugin enable/disable --scope user typically propagates to every profile within seconds without a relaunch (verified 2026-08-22). The mirror adopts first: enabledPlugins keys that exist only in some profile's settings.json (the way claude plugin install writes them) are written back into the default profile before mirroring — consistent values only; cross-profile conflicts stay per-profile behind a standing warning instead of being silently overwritten. The SessionStart converger above covers the same key as part of its whole-settings sync; claude-plugins-sync.py remains the owner of the per-profile known_marketplaces.json structure. skill-install-audit.py reconciles the registry / installed / enabled / Codex-manifest / ~/.agents/skills layers read-only, plus the daemon's pinned runtime version and whether the checkouts it judged everything against are themselves behind. prune-source-sync-backups.py removes only the .source-sync-backups/ buckets git can reproduce; a bucket holding even one blob no repository has is reported and left alone.
• Local source sync keeps approved source-backed routes aligned for each host. Before selecting or repairing entries, read the host-specific activation contract. It owns the manifest fields, marketplace expansion, Claude plugin/direct-link distinction, unresolved-name handling, collision safety, and legacy compatibility. Source registration alone does not choose activation policy; do not hand-create links or repurpose the manifest to manage third-party inventory.
• Sync scripts use a shared cross-process lock. This is required because users often open several provider windows from tmux or multiple terminals at once; concurrent launches must serialize marketplace/cache rewrites while still allowing all profiles to start.
• For the full local-source architecture, read references/local-source-sync-architecture.md before changing these scripts.
• For Skill authoring in an approved independent Fleet clone, use the leased-authoring owner procedure.
• Provider routing is done via ~/.claude/settings/<name>.json, which sets non-secret ANTHROPIC_MODEL and ANTHROPIC_BASE_URL for that window. Deliver credentials through the explicit export binding in setup step 4; existing in-file credentials remain readable for legacy compatibility. That file is a full settings file rather than an env file, and it is the one layer the converger never touches — claude-profile launches with claude --settings ~/.claude/settings/<name>.json, while the converger only ever writes <profile>/settings.json. So anything that has to be per-profile and has to survive every session start belongs here; put it in the profile's own settings.json and the next convergence takes it back. This includes per-profile permissions.deny, such as denying WebSearch and WebFetch.
• Per-profile thinking effort lives in that provider file too. The default profile sets effort per Anthropic model via modelSettings in ~/.claude/settings.json; a third-party profile that needs a different effort pins CLAUDE_CODE_EFFORT_LEVEL (e.g. "max") in its ~/.claude/settings/<name>.json env instead. The provider file is the only layer that can hold that pin: put it in the profile's own settings.json env and the converger deletes it at the next session start (a non-identity env key the default profile doesn't carry is deletion-propagated away); put it in the default profile's env and it applies there and converges into every third-party profile's settings.json — usually wrong, because weaker third-party models benefit from forced max effort exactly when the default flagship no longer does (verified end-to-end 2026-10-06: a session launched via claude-profile reads the pinned value back from its own environment).
• A scripted profile needs its provider settings and its credential binding. Use claude-profile or the registered execution owner so the model, endpoint and authorized token reach the same process. A caller that supplies only CLAUDE_CONFIG_DIR can omit those inputs; Not logged in does not by itself mean a new login or key is needed. Resolve the existing source and reproduce its explicit per-profile export binding first. Legacy in-file tokens remain readable, but new setup must not put a secret in a settings file.
• The converger has no single-profile mode: every invocation covers all of ~/.claude-profiles/* plus $CLAUDE_CONFIG_DIR, and no flag narrows that. To converge one profile on demand, point CLAUDE_PROFILES_ROOT at a directory holding only it, or run --check and read the per-profile lines. The default profile's own files are the source and are never written.