claude-switch-models-setup

Claude Code Multi-Provider Profiles

Overview

This skill creates an isolated-but-shared profile system for Claude Code CLI. Each profile gets its own .claude.json state file (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.

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 the active 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). 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.
• 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 (added 2026-09-03, after adopt-less mirroring was confirmed as the mechanical root cause of recurring skill-visibility losses). 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 is automatic on maintainer machines, but source inventory is not activation policy. Claude plugin cache directories remain source-backed; Codex user Skills are selected explicitly by ~/.config/claude-switch-models-setup/codex-active-skills.json and linked into the official user root ~/.agents/skills. The manifest's optional active_marketplaces names managed marketplaces whose whole current membership is active, for a marketplace whose own charter is "every registered Skill is activated" — the declaration still lives in the manifest, only at marketplace granularity, and every marketplace not named there stays per-skill curated. ~/.codex/skills/.system remains Codex-owned; the repair pass never edits it. After every selected replacement link is verified, the pass creates or confirms only the optional legacy_codex_compat_skills subset as same-source links under legacy ~/.codex/skills; other managed legacy links are reported for reviewed cleanup, never deleted by the background task.
  • The manifest is intentionally fail-fast: missing file, non-array or duplicate name lists, unknown name, a compatibility name absent from active_skills, or the same frontmatter name registered by two different source bundles aborts before root mutation. Explicit JSON null is malformed, not an empty compatibility choice. This prevents a Python dictionary or directory scan order from silently choosing the winner.
  • Pitfalls with daemon-owned symlinks (observed 2026-07): never hand-create a symlink over an existing daemon-owned entry. BSD ln can put the new link inside the target directory, leaving a self-referential stray. Change active_skills for normal activation; when a long-lived hook or process still holds an old ~/.codex/skills/<name> path, add that already-active name to legacy_codex_compat_skills. Verify links with readlink, not ls -la <link>—ls follows the link and can make a failed replacement look successful.
  • Third-party bundles already installed under ~/.agents/skills are outside that manifest's ownership. Do not add them to the source manifest or delete them merely to reduce Codex prompt load. Route “keep the bundle on disk but hide it from Codex” to /daymade-skill:skill-governance; references/local-source-sync-architecture.md records the ownership boundary without duplicating that workflow.
• 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.
• Provider routing is done via ~/.claude/settings/<name>.json, which sets ANTHROPIC_MODEL, ANTHROPIC_BASE_URL, and ANTHROPIC_AUTH_TOKEN for that window.