Skip to main content

​
Multiple Claude Accounts

CCS enables running multiple Claude CLI instances simultaneously with different accounts. Each profile runs in an isolated environment with independent credentials, sessions, and state. Key Feature: Login once per profile → use anywhere, anytime.

​
How It Works

CCS uses CLAUDE_CONFIG_DIR environment variable to create isolated Claude instances: 
# Each profile = separate directory
~/.ccs/instances/work/        # Work account instance
~/.ccs/instances/personal/    # Personal account instance
When you run ccs work "task", CCS:
  1. Points CLAUDE_CONFIG_DIR to ~/.ccs/instances/work/
  2. Claude CLI loads credentials from that directory
  3. All state (sessions, todos, logs) stays isolated

​
Quick Start

​
1. Create Profiles

# Create first profile (will prompt for login)
ccs auth create work
# Complete OAuth login with work account

# Create second profile
ccs auth create personal
# Complete OAuth login with personal account

​
2. Use Profiles

# Use work account
ccs work "review code"

# Use personal account
ccs personal "help with project"

# Check which account is active
ccs work /status    # Shows work account email
ccs personal /status # Shows personal account email

​
3. Concurrent Sessions

# Terminal 1
ccs work "implement feature X"

# Terminal 2 (simultaneously)
ccs personal "research topic Y"

# Both run at the same time with isolated state

​
Profile Management

​
List Profiles

ccs auth list

# Output:
# [*] work (default)
#     Type: account
#     Created: 2025-11-09T10:30:00.000Z
#
# [ ] personal
#     Type: account
#     Created: 2025-11-09T11:15:00.000Z

​
Set Default

ccs auth default work

# Now `ccs` without profile name uses work
ccs "task"  # Uses work account

​
Remove Profile

ccs auth remove personal --force
# Deletes instance and credentials

​
Shared Context Groups (Opt-in)

Available since v7.52.0 — Explicit opt-in required
By default, each profile is isolated. Use context_group to opt-in to sharing project context across multiple accounts.

​
Quick Setup

# ~/.ccs/config.yaml
profiles:
  work:
    type: account
    target: claude
    context_group: "team-alpha"  # Enable shared context

  work-personal:
    type: account
    target: claude
    context_group: "team-alpha"  # Same group = shared context

​
How It Works

Profiles in the same context_group share:
  • Project workspace — commands/, skills/, agents/
  • Session memory — chat history, context
  • Commands and skills — cross-account discovery
Profiles in different groups stay isolated.

​
Use Cases for Shared Context

profiles:
  # Team 1: All share project context
  alice:
    context_group: "feature-team-1"

  bob:
    context_group: "feature-team-1"

  # Team 2: Isolated from Team 1
  charlie:
    context_group: "feature-team-2"

​
Rules

  • context_group is optional (defaults to isolated mode)
  • Must be non-empty string when specified
  • Names are normalized (spaces/hyphens allowed)
  • Can contain letters, numbers, hyphens, underscores, spaces

​
Disabling Shared Context

Remove context_group to go back to isolated mode: 
profiles:
  work:
    type: account
    # Removed context_group line
    # Now isolated again

​
Use Cases

Work vs Personal

Separate client projects from personal work with different subscriptions

Different Subscriptions

Pro account for heavy tasks, free account for light tasks

Team Collaboration

Multiple accounts sharing project context (shared context groups)

Context Isolation

Production debugging vs experimental coding with no history mixing

​
Instance Structure

Each profile gets its own isolated directory: 
~/.ccs/instances/work/
├── .credentials.json      # OAuth credentials (managed by Claude)
├── session-env/           # Chat history & context
├── todos/                 # Task lists
├── logs/                  # Execution logs
├── commands/              # Custom commands
└── skills/                # Custom skills
Key Points:
  • Credentials managed by Claude CLI (not CCS)
  • Each profile requires separate OAuth login
  • State never shared between profiles

​
Limitations

Running the same profile in 2 terminals causes conflicts. Use different profiles for concurrent sessions.
# Terminal 1
ccs work "task1"

# Terminal 2 (will conflict)
ccs work "task2"  # Same session files

# Solution: Use different profiles
ccs work "task1"      # Terminal 1
ccs personal "task2"  # Terminal 2