ccs/docs/concurrent-sessions.md

Concurrent Sessions (v3.0.0)

Overview

CCS v3.0.0 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

Instance Isolation

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

Platform Support

✅ All platforms supported: Linux, macOS, Windows

• Same approach everywhere (unified implementation)
• No platform-specific workarounds needed
• Tested and working on all three platforms

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

Check Account

# See which account a profile is logged into
ccs work /status
# Output shows: email, subscription tier, etc.

ccs personal /status
# Different email/account info

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
├── file-history/          # Edit tracking
├── shell-snapshots/       # Shell state
├── debug/                 # Debug info
├── .anthropic/            # SDK config
├── 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
• Completely isolated environments

Use Cases

1. Work vs Personal

# Work account for client projects
ccs work "implement auth feature"

# Personal account for side projects
ccs personal "help with my portfolio site"

2. Different Subscriptions

# Pro account for heavy tasks
ccs pro "analyze large codebase"

# Free account for light tasks
ccs free "quick question about syntax"

3. Team Collaboration

# Company account
ccs company "review team's code"

# Client account (when working on client's Claude)
ccs client "implement their requirements"

Architecture

Profile Creation Flow

1. User: ccs auth create work
2. CCS creates ~/.ccs/instances/work/ directory
3. CCS spawns Claude with CLAUDE_CONFIG_DIR=~/.ccs/instances/work/
4. Claude detects no credentials
5. Claude prompts OAuth login
6. User completes login
7. Claude saves credentials to instance/.credentials.json
8. Done - profile ready to use

Profile Usage Flow

1. User: ccs work "task"
2. CCS detects "work" is account profile
3. CCS ensures instance exists
4. CCS sets CLAUDE_CONFIG_DIR=~/.ccs/instances/work/
5. CCS executes: claude [args] with env var
6. Claude loads credentials from instance
7. Task executes with work account

Settings Profiles (Backward Compatible)

# GLM and Kimi profiles still work (v2.x approach)
ccs glm "task"  # Uses --settings flag
ccs kimi "task" # Uses --settings flag

# These are NOT account profiles, they're API configurations
# Cannot run concurrently with each other

Performance

Fast Activation

• First use: ~20-35ms (create directories + copy configs)
• Subsequent use: ~5-10ms (just validation)
• No encryption overhead (50-120ms faster than v2.x)

Lightweight

• Memory: ~3-5 KB per activation
• Disk: ~200-700 KB per profile
• I/O: 1 read + 1 write per activation

Limitations

1. Same Profile = No Concurrent

Running the same profile in 2 terminals causes conflicts:

# Terminal 1
ccs work "task1"

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

# Solution: Use different profiles

2. CLAUDE_CONFIG_DIR Compatibility

• Undocumented env var (no official Anthropic support)
• Works on recent Claude CLI versions
• May not work on very old versions
• Solution: Keep Claude CLI updated

3. Global Config Not Synced

Commands/skills copied on profile creation, not synced later:

# If you update ~/.claude/commands/ after creating profile:
# Option 1: Delete and recreate instance
rm -rf ~/.ccs/instances/work
ccs work "task"  # Recreates with latest configs

# Option 2: Manually copy
cp -r ~/.claude/commands/* ~/.ccs/instances/work/commands/

4. No Auto-Cleanup

Sessions/logs accumulate over time:

# Manual cleanup if needed
du -sh ~/.ccs/instances/*  # Check sizes
rm -rf ~/.ccs/instances/work/session-env/*  # Clear sessions
rm -rf ~/.ccs/instances/work/logs/*  # Clear logs

Security

Credentials

• Stored at ~/.ccs/instances/<profile>/.credentials.json
• Managed by Claude CLI (OAuth tokens)
• Permissions: 0600 (owner read/write only)
• Never copied between instances

Directories

• Instance dirs: 0700 (owner access only)
• Isolated per profile
• No cross-contamination

No Encryption Needed

• Credentials live in isolated directories
• OS-level file permissions provide security
• Simpler = less attack surface

Troubleshooting

"Profile not found"

# Create the profile first
ccs auth create <profile-name>

"Claude prompts for login"

Normal behavior on first use - complete OAuth flow:

ccs auth create work
# Follow OAuth prompts

"CLAUDE_CONFIG_DIR not working"

# Check Claude CLI version
claude --version

# Update to latest
# (Installation varies by platform)

Check Account Info

# See which account is logged in
ccs work /status
# Shows: email, subscription, organization

# If wrong account, recreate profile
ccs auth remove work --force
ccs auth create work  # Login with correct account

Migration from v2.x

Breaking Changes

1. No vault - credentials in instances
2. Must login per profile (no credential copying)
3. Command changed: auth save → auth create

Migration Steps

# 1. Backup old data (optional)
mv ~/.ccs/profiles.json ~/.ccs/profiles.json.v2

# 2. Remove old profiles
ccs auth remove work --force
ccs auth remove personal --force

# 3. Recreate with v3.0.0
ccs auth create work      # Login with work account
ccs auth create personal  # Login with personal account

# 4. Verify
ccs auth list
ccs work /status
ccs personal /status

# 5. Test
ccs work "hello"
ccs personal "hello"

Advanced

Manual Instance Inspection

# View instance structure
tree ~/.ccs/instances/work/

# Check credentials (OAuth JSON)
cat ~/.ccs/instances/work/.credentials.json

# Check profile metadata
cat ~/.ccs/profiles.json

Profile Metadata

{
  "version": "2.0.0",
  "profiles": {
    "work": {
      "type": "account",
      "created": "2025-11-09T10:30:00.000Z",
      "last_used": "2025-11-09T15:45:00.000Z"
    },
    "personal": {
      "type": "account",
      "created": "2025-11-09T11:15:00.000Z",
      "last_used": "2025-11-09T14:30:00.000Z"
    }
  },
  "default": "work"
}

Force Recreate Instance

# Delete instance (keeps profile metadata)
rm -rf ~/.ccs/instances/work

# Next use recreates fresh instance
ccs work "task"
# Will prompt for login again

See Also

• System Architecture
• Codebase Summary
• Project Overview