Claude Profile Manager docs

v1.2.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 Buy me a beer 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. Claude Profile Manager does not modify onboarding state.

  1. 01

    Install globally

    Install the public package, then validate the environment.

    Terminal 
    npm install -g @nexkit/claude-profile-manager

    Environment check 
    claude-profile-manager doctor

  2. 02

    Create an authorized lane

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

    Create + launcher + login 
    claude-profile-manager 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.

Upgrading from Profile Switcher?

Version 1.2.0 renames @nexkit/profile-switcher to @nexkit/claude-profile-manager. Existing profiles, mappings, and launchers keep working; nothing is copied or moved. Follow the migration steps.

03 / COMMAND INDEX

One surface. Four jobs.

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

01 Profiles

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

02 Launch

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

03 Maintenance

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

04 Launchers

claude-profile-manager command create <profile> [profile-command]
Create or rename one managed launcher.
claude-profile-manager command remove <profile-command>
Remove one managed launcher while keeping profile data.
claude-profile-manager command list
Show launcher-to-profile mappings and state.
claude-profile-manager command sync
Rebuild managed launchers for existing named profiles.
claude-profile-manager 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 claude-profile-manager. 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~/.claude-profile-manager/<name>CLAUDE_CONFIG_DIR
MAPPINGS~/.claude-profile-manager/commands.jsonlauncher registry
LAUNCHERSglobal npm executable directory.cmd or POSIX

Compatibility: Claude Profile Manager uses the first storage root that exists: ~/.claude-profile-manager, then ~/.profile-switcher, then the legacy ~/.claude-profiles root with its .npm-commands.json manifest. Fresh installs use the paths shown above.

  • Credentials: never printed, copied, moved, bundled, or deleted.
  • Sessions, skills, and plugins: isolated until you explicitly link them.
  • 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.

claude-profile-manager doctor
claude-profile-manager command list
claude-profile-manager command sync

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

Profile is not signed in 
claude-profile-manager status team
claude-profile-manager login team

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

Profile state looks wrong 
claude-profile-manager diagnose team

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

Sharing exits with code 2

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

claude-profile-manager 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 
claude-profile-manager command clean
npm uninstall -g @nexkit/claude-profile-manager

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

08 / MIGRATION

New name. Same lanes.

Version 1.2.0 renames @nexkit/profile-switcher to @nexkit/claude-profile-manager. Replace the package; nothing is copied or moved.

From @nexkit/profile-switcher 
npm uninstall -g @nexkit/profile-switcher
npm install -g @nexkit/claude-profile-manager
claude-profile-manager command sync

claude-profile-switcher and profile-switcher remain aliases of claude-profile-manager. An existing ~/.profile-switcher root stays active. Generated launchers keep working because they only set CLAUDE_CONFIG_DIR and call claude.

From the retired @nathanpixodeo/claude-profile-manager package

Uninstall the old package, install @nexkit/claude-profile-manager, then run claude-profile-manager command sync. Existing ~/.claude-profiles data, its .npm-commands.json manifest, and claude-* launchers remain readable. Do not delete ~/.claude-profiles when migrating.

09 / 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.