Claude Code Multi-Profile, v2: таза XDG-архитектура

Бір ай бұрын мен бір машинада екі Claude Code аккаунтын қатар іске қосу туралы пост жарияладым — жеке және жұмыс, CLAUDE_CONFIG_DIR мен shell alias арқылы. Тәсіл жұмыс істеді. Бәрі істеуге тиісін істеді.

Бірақ бір ай нақты қолданыстан кейін мен сол пост қамтымаған бірнеше елеулі мәселеге тап болдым. Ең үлкені — Claude Code-тың жасырын ерекшелігі, оған кездейсоқ тап болдым: Gmail MCP-ін қосқанымда, ол бес минуттан соң профилімнен "жоғалып кетті". Бүгін мен бәрін жаңа архитектураға қайта құрдым — XDG-үйлесімді, symlink пен gum арқылы интерактивті профиль таңдағышы бар. Бұл — v2, теориялық жақсарту емес, нақты тәжірибеден шыққан эволюция.

Не мазалай бастады

Төрт нәрсе. Алғашқы үшеуі — реттілік, көріну және масштаб туралы. Төртіншісі — бірден байқамаған нағыз архитектуралық тұзақ. Оларды ретімен қарастырамын, өйткені ақыр соңында дәл төртіншісі қайта құруға мәжбүрледі.

1. $HOME-да екі бөлек қалта — бұл былық

~/.claude мен ~/.claude-promova — $HOME түбірінде қатар тұрған екі dotfolder. XDG Base Directory Specification конфигтер ~/.config/ ішінде тұруға тиіс дейді. Тікелей home-да шашылып жатқан dotfile қалталары — уақыт өте $HOME-ды қоқыс тартпасына айналдыратын антипаттерн. Косметикалық, әрине, бірақ ls -la ~ көрген сайын мазалайтын.

2. Белсенді профильдің көрнекі растамасы жоқ

claude-ты іске қосамын да, қай профиль белсенді екенін білмеймін — сессия ішінде claude config list орындағанша. Қай терминалда нені іске қосқанымды ұмытсам, тексеруге тура келетін. Ұсақ нәрсе, бірақ personal + жұмыс екі қойындыда қатар жүргенде ол жиналып қалады.

3. Alias-тар масштабталмайды

Екі профиль — claude мен claude-promova — жарайды. Үшіншісін қосасың (фриланс клиенті) — үшінші alias керек. Төртіншісін — төртіншісі. Жарты жылдан соң қандай alias-тар жасағанымды есіме де түсіре алмас едім.

4. ~/.claude.json ішіндегі жасырын тұзақ

Ал міне, қайта құрудың нағыз себебі осы. Claude Code-та конфигурацияның екі түрлі орны бар, әрі құжаттама бұл туралы айқайламайды: ~/.claude/ — projects/, sessions/, hooks/, skills/ жататын каталог. Әрі бөлек — ~/.claude.json, тікелей $HOME түбіріндегі файл, онда oauthAccount, mcpServers, projects тарихы, skillUsage және нақты live күйдің тағы шамамен 40 өрісі тұрады.

claude mcp add --scope user командасы дәл сол home-түбіріндегі ~/.claude.json-ға жазады, ~/.claude/.claude.json-ға да, профиль каталогына да емес. Мен мұны білмедім. Бір күні тап болғанша.

Ашылу: Gmail MCP неге "жоғалды"

Бүгін таңертең мен Claude Code-та Gmail MCP-ін баптап жатырмын. Әдеттегі баптау: Google Cloud жобасы, OAuth деректемелері, claude mcp add gmail --scope user -- npx -y @gongrzhe/server-gmail-autoauth-mcp. Бәрі жақсы. Сессияны қайта іске қостым — жұмыс істейді, поштаны оқып, хаттарға жауап беріп отырмын. Бір сағаттан соң біз alias-тарды gum профиль таңдағышы бар функцияға рефакторлай бастадық, содан кейін бәрін XDG-ге көшірдік. Мен mv ~/.claude → ~/.config/claude-profiles/personal жасадым, CC-ды қайта іске қостым, мәзірден personal-ды таңдадым. Ал жаңа сессияда /mcp аштым:

figma            (failed)
playwright-test
claude.ai Notion

gmail жоқ. vaultforge жоқ. Тек үш сервер, оның біреуі тіпті failed болған. Ал мен Gmail-ды жаңа ғана қосқам. Сол уақытта басқа терминалдағы сессия (жұмыс профилі) Gmail мен Vaultforge-ті еш мәселесіз көрсетіп тұрды.

Мен қаза бастадым да, машинамда .claude.json деп аталатын үш түрлі файл барын таптым:

Міне, осы. Дәл осы — сол архитектуралық тұзақ:

1. claude mcp add --scope user CLAUDE_CONFIG_DIR-ге қарамастан әрдайым home-түбіріндегі ~/.claude.json-ға жазады
2. CLAUDE_CONFIG_DIR орнатылғанда Claude Code $CLAUDE_CONFIG_DIR/.claude.json-ды оқиды — профиль ішіндегі файлды
3. "user-scope MCP-тер" жазбалары мен "профиль MCP-тері" жазбалары бірдей атаулы бөлек файлдарда тұрады — әрі оларды шатастыру оңай

Менің жағдайымда ~/.claude.json (home-түбір, 113 KB) тірі, өзекті күй болды — gmail, vaultforge, OAuth сессиясы, бәрімен. Ал ~/.config/claude-profiles/personal/.claude.json (29 KB) ескі snapshot болып шықты, ол бұрынырақтан ескі ~/.claude/-та жатқан — бәлкім ескі CC нұсқасы сонда жазған, бәлкім плагин. Екі файлға да jq -r 'keys[]' қолданғанда home-түбірдегі нұсқада snapshot-та жоқ 41 бірегей кілт барын көрсетті.

Ал бұл 41 кілт — қоқыс емес. Бұл — Claude Code-тың нақты күйі:

• skillUsage — skill-дерді қолдану статистикасы
• githubRepoPaths — жоба навигациясына арналған репозиторийлер кэші
• cachedGrowthBookFeatures + cachedStatsigGates — feature flag-тер (оларсыз CC әр іске қосуда жаңасын тартады)
• hasShownOpus45Notice, hasShownOpus46Notice, hasShownS1MWelcomeV2 — UI флагтары (оларсыз модаль терезелер келесі іске қосуда қайта шығады)
• lastPlanModeUse, feedbackSurveyState, installMethod — onboarding және UX күйі

Егер жай ғана mv ~/.claude ~/.config/claude-profiles/personal merge-сіз жасасаң — бұның бәрін жоғалтасың. Welcome модальдары қайта оралады, githubRepoPaths іздеуі қайта жүреді, әрбір сауалнама сұрауы қайта келеді. Мен мұны істей жаздадым.

Жаңа архитектура

Бәрі ~/.config/ ішіндегі бір ата-каталогтың астында тұрады, дәл XDG қалағандай. Әр профиль өзіне-өзі жеткілікті — өзінің .claude.json-ын қоса, толық күйі бар. ~/.claude кері үйлесімділік үшін personal профильге symlink ретінде қалады.

~/.config/claude-profiles/
├── personal/
│   ├── .claude.json          ← full live state + MCP list (113 KB)
│   ├── projects/, sessions/, hooks/, skills/, ...
│   └── CLAUDE.md
└── promova/
    ├── .claude.json          ← work state + work MCPs (41 KB)
    └── projects/, sessions/, agents/, skills/, ...

~/.claude  →  symlink to ~/.config/claude-profiles/personal/

$HOME түбірінде ешқандай .claude.json жоқ. Әр профиль — бәрін ұстайтын бөлек оқшауланған каталог: projects/sessions қалталары да, MCP серверлері мен OAuth токендері бар сол файл да. Профильге бір ғана шындық көзі.

Symlink неге дәл personal-ға бағытталған

~/.claude/ жолын hardcode ететін бәрі — ескі скрипттер, плагиндер, Claude Code IDE кеңейтімдері, claude-powerline.json сияқты statusline конфигтері — өзгеріссіз жұмысын жалғастырады. Symlink personal профильге сілтейді. Егер кездейсоқ command claude-ты (wrapper функциясын айналып өтіп) іске қоссаң — default-жол іздеуі арқылы тағы да personal-ға түсесің. Personal бұрынғысындай "үнсіз default" болады, бірақ енді физикалық түрде XDG орнында тұрады.

Іске қосудағы интерактивті таңдағыш — функция + gum

Alias-тардың орнына — ~/.zshrc ішіндегі claude() функциясы, ол gum (Charm-ның TUI көмекшісі) арқылы көрсеткі пернелермен басқарылатын мәзір көрсетеді. Функция claude шақыруын shell деңгейінде ұстап қалады, профиль таңдауға мүмкіндік береді және сәйкес CLAUDE_CONFIG_DIR-мен command claude-ты іске қосады. Мұнда command маңызды — ол wrapper функциясын айналып өтіп, нақты бинарьді шақырады.

# brew install gum

# Claude Code: profile picker on launch
claude() {
  local profile
  profile=$(gum choose \
    --header "Claude profile:" \
    --cursor "▸ " \
    --selected.foreground 212 \
    --cursor.foreground 212 \
    --header.foreground 244 \
    "personal" "promova") || return
  case "$profile" in
    personal) CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/personal" command claude "$@" ;;
    promova)  CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/promova"  command claude "$@" ;;
  esac
}

Іске қосқанда былай көрінеді:

Claude profile:
▸ personal
  promova

↑↓ — жылжу үшін, Enter — таңдау, Esc — бас тарту (сонда Claude жай ғана іске қосылмайды). Профиль әрдайым көрініп тұрады — ұмыту мүмкін емес.

Нөлден бастап (миграциялайтын v1 жоқ)

Егер сен ескі екі-қалта + alias хагін қолданып жүрсең — төмендегі миграция скриптіне өт. Бұл бөлім — нөлден таза құрастыру: жаңа машина немесе қарапайым қолданыстан қалған әдепкі ~/.claude. Алдымен пішінін шеш: бір аккаунт әрі бірнеше профиль (жобаларды және олардың MCP жиынтығын оқшаулау үшін — жиі кездесетін жағдай), әлде профильге шынымен бөлек аккаунттар (жеке vs жұмыс).

1. Каталогтарды орналастыр

# prerequisites
brew install gum jq

# 1. XDG parent for all profiles
mkdir -p ~/.config/claude-profiles

# 2. fold an existing default install in as your first profile (no-ops on a fresh machine)
if [ -d ~/.claude ] && [ ! -L ~/.claude ]; then
  mv ~/.claude ~/.config/claude-profiles/personal
  [ -f ~/.claude.json ] && mv ~/.claude.json ~/.config/claude-profiles/personal/.claude.json
fi

# 3. one directory = one profile
mkdir -p ~/.config/claude-profiles/personal ~/.config/claude-profiles/work

# 4. these files will hold OAuth tokens — lock them down
chmod 600 ~/.config/claude-profiles/*/.claude.json 2>/dev/null

Бір профильге бір каталог, жалғыз XDG түбір-каталогының астында. Егер сен Claude Code-ты бұрын қолданған болсаң, сниппет бұрыннан бар ~/.claude-ты personal ретінде ішіне жинайды әрі онымен бірге home-түбіріндегі ~/.claude.json live күйін де көшіреді; шынымен жаңа машинада бұл жолдар жай ғана ешнәрсе істемейді. Қалғаны — алғаш іске қосқанда өздігінен толатын бос каталогтар — ал chmod 600 маңызды, өйткені бұл файлдарда ақыр соңында OAuth токендері жатады.

2. Әр профильді аутентификацияла

# launch each profile once and authenticate it
CLAUDE_CONFIG_DIR=~/.config/claude-profiles/work claude
#   → run /login in the session, sign in, done.
# Same account for every profile? One /login is enough — macOS keeps it in the
# shared Keychain, so the other profiles are already authenticated.

Әр профильді өзінің CLAUDE_CONFIG_DIR-мен бір рет іске қосып, /login орында. Басты нюанс: егер барлық профиль бір аккаунтты пайдаланса, тек бір рет кіресің — macOS тіркелгі деректемесін Keychain-нің жалғыз ортақ жазбасында сақтайды, сондықтан басқа әр профиль автоматты түрде аутентификацияланады.

Профильге бөлек аккаунттар — қиынырақ жол: Keychain-нің сол ортақ жазбасы бір ғана логинді ұстайды, сондықтан екінші аккаунтпен басқа профильге кіру біріншісін қайта жазып жіберуі мүмкін. Егер бұл сенің жағдайың болса — бір машинада екі Claude аккаунтын іске қосу бөлімінің арнайы нұсқаулығын ұста әрі сенер алдында өзіңнің Claude Code нұсқаңда тіркелгі деректемелерінің оқшаулануын тексер.

3. Symlink пен picker

# personal becomes the default target of ~/.claude (back-compat)
ln -s ~/.config/claude-profiles/personal ~/.claude

# add the claude() gum picker from the architecture section to ~/.zshrc, then:
source ~/.zshrc
claude        # ← now shows the profile menu on every launch

Осы жолды hardcode ететін бәрі жұмысын жалғастыруы үшін ~/.claude-ты personal профильге бағытта, содан кейін жоғарыдағы архитектура бөліміндегі claude() gum picker-ін ~/.zshrc-ге тастап қой. Қайта жүктегеннен кейін claude әр іске қосуда профиль мәзірін көрсетеді — миграцияланған баптаумен бірдей соңғы күй, тек нөлден құрастырылған.

4. Әр профильдің MCP-ін сарала

Соңында, әр профильге тек оған көрінуге тиіс құралдарды ғана бер: сол профильдің settings.json-ында disableClaudeAiConnectors: true қой да, оған не қажет болса, claude mcp add арқылы қайта қос — дәл жоғарыдағы конекторлар бөліміндегідей. Дәл осы он алмастырмалы профильді мақсатқа арнап құрылған он профильге айналдырады.

Миграция скрипті

Мұны оқып отырып, ескі схемадан көшкісі келетіндерге арналған. Ең сыни қадам — екіншісі: ол home-түбіріндегі ~/.claude.json-ды personal профильде бұрыннан бары бар нәрсемен merge жасайды, mcpServers тізімдерін біріктіреді. Бұл қадамсыз профиль MCP-терін де, бүкіл live күйін де жоғалтады.

# 1. Move existing dotfolders into a new XDG-style parent.
#    APFS mv is an inode rename — safe even if claude --resume is open in
#    another terminal, file descriptors stay alive on the same inode.
mkdir -p ~/.config/claude-profiles
mv ~/.claude          ~/.config/claude-profiles/personal
mv ~/.claude-promova  ~/.config/claude-profiles/promova   # rename as needed

# 2. CRITICAL: merge ~/.claude.json (the live state — likely 100+ KB) into
#    the personal profile, unioning mcpServers so no MCP is dropped.
jq -s '.[0] * {mcpServers: (.[0].mcpServers + .[1].mcpServers)}' \
  ~/.claude.json \
  ~/.config/claude-profiles/personal/.claude.json \
  > /tmp/personal-merged.json
mv /tmp/personal-merged.json ~/.config/claude-profiles/personal/.claude.json

# 3. Fix permissions — jq+mv inherits umask (likely 644), but this file
#    holds OAuth tokens. Tighten to 600 immediately.
chmod 600 ~/.config/claude-profiles/personal/.claude.json

# 4. Back up the orphaned home-root file (delete once verified)
mv ~/.claude.json ~/.claude.json.migrated.bak

# 5. Symlink for backward compatibility (statusline configs, IDE plugins,
#    anything that hardcodes ~/.claude/ keeps working unchanged)
ln -s ~/.config/claude-profiles/personal ~/.claude

Рұқсаттар туралы үшінші қадам өз алдына маңызды. jq | mv umask 644-пен (бәріне оқылатын) файл жасайды. Онда OAuth токендері бар. Merge-тен кейін бірден chmod 600 жасау міндетті.

Миграциядан кейін — барлық белсенді Claude сессияларын жауып, қайта аш, shell-ды қайта жүкте (source ~/.zshrc немесе жаңа терминал), claude-ты іске қос, профиль таңда, claude mcp list арқылы бүкіл MCP орнында екенін тексер. Бәрі жақсы болса — ~/.claude.json.migrated.bak-ты өшір. Бірдеңе дұрыс болмаса — қайтару тривиалды: mv ~/.claude.json.migrated.bak ~/.claude.json да symlink-ты алып таста.

Бонус: профиль сайын MCP конекторлары (ұйымың оларды ортақтастырғанда)

Жоғарыдағы архитектура оқшаулаудың екінші осін ашады — әрі дәл осы менің шын мәнінде ең көп қолданатыныма айналды. Егер сенің Claude аккаунтың бір ұйымға тиесілі болса, ұйым қашықтағы MCP конекторларының ортақ жиынтығын тарата алады (Figma, тапсырма трекері, метрика бэкенді, дерекқор шлюзі, CMS…). Claude Code ұйым қосқан әрбір конекторды әрбір сессияға автоматты түрде тартады, өйткені олар сен іске қосқан каталогқа емес, аккаунтқа байланған.

Екі-үш конектормен бұл жақсы. Он жоба мен ондаған ұйым конекторымен бұл жарамай қалады: әр сессия өзі мүлдем тиіспеуге тиіс құралдарды жүктейді. Бұл модельдің құрал тізіміндегі шу, бұл бос кеткен контекст, әрі — шын ауыртатын тұсы — сессияға басқа жобаға тиесілі жүйеге қол созуға мүмкіндік береді. B жобасымен жұмыс істеп жатқанда A жобасының конекторы тіпті болмауға тиіс.

Авто-тартуды өшір де, содан соң сарала

Тетік — жалғыз баптау, disableClaudeAiConnectors (Claude Code v2.1.182+). Ол кез келген баптау scope-ында тұрады — оның ішінде профильдің өзіндік settings.json-ында да — сондықтан ол әр CLAUDE_CONFIG_DIR сайын. Оны true қой да, сол профиль ұйым конекторларын автоматты тартуды толық тоқтатады:

{
  "disableClaudeAiConnectors": true
}

Содан кейін тек сол профильге шын қажет конекторларды қайта қосасың. Айқын қосылған серверлерді флаг тиіспейді, сондықтан олар әдеттегідей жүктеледі — нәтижесі профиль сайын сараланған ішкі жиын:

# add back only what this profile uses — writes to the profile's own .claude.json
claude mcp add --scope user --transport http figma  https://<your-figma-connector>/mcp
claude mcp add --scope user --transport http linear https://<your-linear-connector>/mcp

Сол аккаунт, сол ұйым каталогы — бірақ әр профиль тек өз бөлігін көреді, оған қоса саналы түрде қайталайтын ортақ конекторларды (тапсырма трекері әдетте бәрінде тұруға лайық).

Сенер алдында мұны тексердім

Құжаттаманың сөзіне сеніп қалғым келмеді, сондықтан бір профильде таза A/B жүргіздім — сол аккаунт, сол OAuth токені, жалғыз айырмашылық — сол бір settings.json:

profile WITHOUT the flag
  /mcp → Figma, Linear, Grafana, Postgres, Notion, Sentry, …   (entire org catalog)

same account, profile WITH  disableClaudeAiConnectors: true
  /mcp → (nothing auto-loaded)

…then  claude mcp add  Figma + Linear
  /mcp → Figma, Linear                                         (exactly the curated subset)

Ол уәде еткенін тап-тура істейді. Оған арқа сүйемес бұрын білуге тұрарлық екі ескертпе:

• OAuth конекторын қайта қосу бір интерактивті логинді талап етеді. URL-дегі кілт арқылы аутентификацияланатын конекторлар claude mcp add арқылы толықтай автоматты қайтады. OAuth артындағы конекторлар сол профильде оларды алғаш қолданғанда браузерде бір реттік аутентификация сұрайды.
• claude mcp list ұйым конекторларын мүлдем көрсетпейді — тек жергілікті анықталған және айқын қосылған серверлерді. Автоматты тартылғандары тек тірі сессияда /mcp арқылы көрінеді. mcp list олардан "бос" көрінгенде абыржыма.

Не аласың

• $HOME-дағы екі dotfolder орнына бір ата-каталог — XDG-үйлесімді
• Symlink ~/.claude/-ты hardcode ететін бәрімен үйлесімділікті сақтайды
• Әр профиль өзіне-өзі жеткілікті — оның толық күйі мен MCP-тері өзінің .claude.json-ында тұрады
• Профильге бір ғана шындық көзі — home-түбіріндегі профильдікінен үнсіз ажырап бара жатқан жетім конфиг енді жоқ
• Сезімтал деректердің (oauthAccount, токендер) рұқсаттары кепілді түрде 600
• Әр іске қосуда белсенді профильдің көрнекі растамасы — қай профиль белсенді екенін ұмыту мүмкін емес
• Үшінші профиль қосу = функцияның case-іне бір жол қосу, жаңа alias клондап, оның атын жаттау емес

Кемшін тұстары

Ашығын айтқым келеді. Бұл — тегін жақсарту емес; онымен бірге бірнеше ымыраға келу де келді, әрі оларды алдын ала білген жөн.

• gum — қосымша тәуелділік (brew install gum, ~13 MB). Егер оны орнатқың мүлдем келмесе — zsh-тегі select-ке немесе қарапайым read-ке қайтуға болады. Жұмыс істейді, бірақ сондай әдемі көрінбейді әрі көрсеткі пернелермен навигация жоқ.
• Әр іске қосуда бір Enter басу. claude-ты күніне ондаған рет іске қосатындарға бұл ашуландыруы мүмкін. Балама төменде (direnv).
• ~/.claude → personal symlink-і personal-ды default етеді. Жұмыс профилін default ету керек болса, symlink-ты қайта бағыттауға тура келеді (ln -sf). Қиын емес, бірақ бұл "ұмыт та кет, ешнәрсе бұзылмайды" емес.
• Symlink теориялық тұрғыда бұзылуы мүмкін, егер бір құрал ~/.claude.json-ды temp+rename паттерні (write-file-atomic) арқылы атомарлы қайта жазса. Іс жүзінде Claude Code-тың өзі олай істемейді, бірақ үшінші тарап плагиндерін орнатсаң — тексер.
• Егер профильдерде түрлі жоспарлы түрлі Anthropic аккаунттарың болса — ауысқаннан кейін Claude Code OAuth күйін синхрондап жатқанда секундтан аз кідіріс болуы мүмкін. Менің қолданысымда байқалмайды, бірақ ол нөл емес.

Қарастырған баламаларым

direnv — әр жобаның түбіріндегі .envrc негізінде CLAUDE_CONFIG_DIR-ды автоматты орнатады. Нөл интерактив, нөл шерту. Кемшілігі: әр work root-қа .envrc қою керек, ал танылмаған қалтада claude-ты іске қоссаң — default профильді аласың (ол қалағаның болмауы мүмкін). Аз ғана work root-та тұратын әрі ешқашан ештеңе шерткісі келмейтіндер үшін direnv шынымен жақсырақ.

Symlink негізіндегі ауыстыру (~/.claude symlink-ын қайта бағыттау арқылы бір ғана белсенді профиль) — оны да қарастырдым да, бірден бас тарттым. Түрлі профильді екі терминалды бір мезгілде ашық ұстай алмайсың — жаһандық "ағымдағы" біреу-ақ. Мен үшін бұл — deal-breaker.

Қорытынды

v2 — жай ғана v1 үстіндегі жақсырақ UX емес. Бұл — Claude Code-та жасырын архитектуралық ерекшелік бар екенін мойындау (~/.claude.json — home-түбіріндегі бөлек файл, оған --scope user командалары CLAUDE_CONFIG_DIR-ге қарамастан жазады), әрі профильдер арасында нағыз оқшаулау керек болса, оны ескеруге тура келеді. Бірінші тәсіл (~/.claude + ~/.claude-promova + alias) 80%-ға жұмыс істеді, бірақ қалған 20% профильдер арасындағы күйдің үнсіз ығысуы түрінде көрінді. Енді ол ескерілген. Егер жаңа бастап жатсаң — бірден v2-ден баста. Егер v1-де отырсаң — миграция скрипті жоғарыда, көшу бес минут алады да, ештеңе бұзбайды (дәл jq merge — сені күйден айырылудан құтқаратын қадам).