Profile Switcher docs

v1.0.0 field manual

Operate profiles.
Keep lanes clear.

Install, create, launch, diagnose, share, and remove profile commands without crossing account or data boundaries.

Start in three steps Open command index

01Install once

02Name a lane

03Launch anywhere

00Background services

01 / REQUIREMENTS

Check the ground first.

Three tools must resolve before a profile command can launch.

Node.js 22+

Node.js 24 LTS recommended. npm must be available in the same terminal.

Claude Code

The official claude executable must already resolve on PATH.

Supported OS

Windows 10/11/Server, Node-supported Linux, or Node-supported macOS.

Windows prefix check

If npm prefix -g contains &, configure a writable prefix without shell metacharacters before installing. Spaces are supported.

02 / QUICK START

First profile in three moves.

The combined add command creates the directory and launcher, then opens Claude Code's official login flow. Profile Switcher does not modify onboarding state.

  1. 01

    Install globally

    Install the public package, then validate the environment.

    Terminal 
    npm install -g @nexkit/profile-switcher

    Environment check 
    profile-switcher doctor

  2. 02

    Create an authorized lane

    team becomes the profile name; profile-team becomes its direct launcher.

    Create + launcher + login 
    profile-switcher add team --command profile-team --login

  3. 03

    Launch from any project

    Generated launchers forward Claude arguments and preserve Claude's exit code.

    Named launcher 
    profile-team
profile-team --continue
profile-team --resume

Keep the default lane intact

Run native claude for the reserved max profile at ~/.claude. Named launchers use isolated directories.

Migrating from the retired npm package?

Uninstall the old package, install Profile Switcher, then run profile-switcher command sync. Existing ~/.claude-profiles data, manifests, and claude-* launchers remain readable; nothing is copied or moved.

03 / COMMAND INDEX

One surface. Four jobs.

Run profile-switcher --help for the same canonical command surface in your terminal.

01 Profiles

profile-switcher
Open the interactive terminal menu when a TTY is available.
profile-switcher list
List profile name, authentication state, and directory.
profile-switcher add <profile> [--command <profile-name>] [--login]
Create an isolated profile and managed launcher; optionally authenticate immediately.

02 Launch

profile-switcher run <profile> [--] [claude arguments...]
Launch a profile and forward the complete Claude argument array.
profile-switcher continue <profile>
Launch with --continue.
profile-switcher resume <profile>
Launch with --resume.
profile-switcher login <profile>
Run Claude Code's official login flow. Re-login for reserved max is blocked.
profile-switcher status <profile>
Run Claude Code authentication status inside the selected profile.

03 Maintenance

profile-switcher diagnose <profile>
Inspect authentication and shared-directory state without modifying profile metadata.
profile-switcher share-sessions <profile> --confirm-same-owner [--backup-existing]
Link default project sessions after explicit ownership and backup checks.
profile-switcher share-skills <profile> --confirm-same-owner [--backup-existing]
Link default user skills under the same safety rules.
profile-switcher doctor
Check Node.js, npm, Claude Code, storage, and command-directory readiness.

04 Launchers

profile-switcher command create <profile> [profile-command]
Create or rename one managed launcher.
profile-switcher command remove <profile-command>
Remove one managed launcher while keeping profile data.
profile-switcher command list
Show launcher-to-profile mappings and state.
profile-switcher command sync
Rebuild managed launchers for existing named profiles.
profile-switcher command clean
Remove generated launchers but preserve mappings for reinstall.
Using legacy v2 flags?

--list, --use, --diagnose, sharing flags, and command-management flags remain supported through profile-switcher. The retired onboarding-repair behavior is intentionally unavailable.

04 / ISOLATION MAP

Know what lives where.

Profile configuration stays local. Launchers route; they do not merge accounts.

DEFAULT / MAX~/.claudenative claude
NAMED PROFILE~/.profile-switcher/<name>CLAUDE_CONFIG_DIR
MAPPINGS~/.profile-switcher/commands.jsonlauncher registry
LAUNCHERSglobal npm executable directory.cmd or POSIX

Compatibility: when ~/.claude-profiles already exists, Profile Switcher keeps using that legacy root and its .npm-commands.json manifest. Fresh installs use the paths shown above.

  • Credentials: never printed, copied, moved, bundled, or deleted.
  • Sessions and skills: isolated until you explicitly link them.
  • Plugins, history, and state: remain inside each profile directory.
  • Billing and limits: unchanged by separate directories or launchers.

05 / CONTROLLED SHARING

Link data only when ownership matches.

Sharing uses an NTFS junction on Windows or a directory symbolic link on Linux/macOS.

Existing local data stops the command

Exit code 2 means nothing changed. Close other Claude sessions, verify disclosure rights, then rerun with --backup-existing. Existing data moves to a timestamped, recoverable backup before linking.

Never open the same shared session concurrently from two profiles. Never link across people, employers, customers, or organizations without every required right and approval.

06 / TROUBLESHOOTING

Read the lane before repairing it.

Start with doctor, then use the narrow check matching the symptom.

doctorstatusdiagnoserepair
Generated command is not found

Check environment and mapping state, then rebuild managed launchers.

profile-switcher doctor
profile-switcher command list
profile-switcher command sync

Inspect resolution with where.exe profile-team on Windows or command -v profile-team on Linux/macOS.

Profile is not signed in 
profile-switcher status team
profile-switcher login team

Login uses Claude Code's official flow. Re-login for reserved max is intentionally blocked.

Profile state looks wrong 
profile-switcher diagnose team

Diagnosis is read-only. Profile Switcher never edits Claude Code onboarding state or credentials.

Sharing exits with code 2

Existing local sessions or skills were detected. Close Claude sessions, review the boundary, then opt into a recoverable backup:

profile-switcher share-sessions team --confirm-same-owner --backup-existing
Windows global npm commands fail before launch 
npm prefix -g

If the prefix contains &, move it to a writable path without shell metacharacters and ensure that directory is on PATH.

07 / UNINSTALL

Remove launchers. Keep profile data.

Clean generated commands before uninstalling the npm package.

Safe removal order 
profile-switcher command clean
npm uninstall -g @nexkit/profile-switcher

Retained: profile directories, command mappings, sessions, state, skills, and credentials. No lifecycle script deletes them.

08 / AUTHORIZED USE

Isolation is not a limit bypass.

Use only accounts you own or are explicitly authorized to administer.

Separate directories do not aggregate, extend, evade, or alter billing, subscription allowances, rate limits, bans, safeguards, product restrictions, or regional access.

The tool does not proxy, intercept, modify, or automate Anthropic requests. Authentication remains inside Claude Code.

Read: Packaged Notice, Consumer Terms, Commercial Terms, Usage Policy, and Supported Regions, Claude Code legal guidance, and Trademark Guidelines.