ccs/docs/session-sharing-technical-analysis.md

Session Sharing Technical Analysis

Last Updated: 2026-02-26

Summary

CCS supports practical cross-account continuity by sharing workspace context files between selected accounts, while keeping credentials isolated per account.

This is implemented as a context policy per account:

• isolated (default): account keeps its own workspace context
• shared + standard (default): account workspace context is linked to a shared context group
• shared + deeper (advanced opt-in): account also shares continuity artifacts

Why This Is Safe Enough

CCS only shares workspace context paths (project/session context files). It does not merge or copy authentication credentials between accounts.

Credential storage remains per account instance.

Implementation Model

Account metadata is stored in ~/.ccs/config.yaml:

accounts:
  work:
    created: "2026-02-24T00:00:00.000Z"
    last_used: null
    context_mode: "shared"
    context_group: "team-alpha"
    continuity_mode: "deeper"

Rules:

• context_mode must be isolated or shared
• context_group is required when context_mode=shared
• continuity_mode is valid only when context_mode=shared (standard or deeper)
• group normalization: trim, lowercase, internal spaces -> -
• group must start with a letter and only include [a-zA-Z0-9_-]
• max length: 64

Deeper continuity links these directories per context group:

• session-env
• file-history
• shell-snapshots
• todos

.anthropic and account credentials remain isolated.

Cross-Profile Inheritance (API / CLIProxy / Copilot)

You can explicitly map non-account profiles (including default) to reuse continuity artifacts from an account profile:

continuity:
  inherit_from_account:
    glm: pro
    gemini: pro
    copilot: pro

Behavior:

• Applies only when running Claude target (ccs <profile> or --target claude)
• Does not change provider credentials or API routing
• Reuses CLAUDE_CONFIG_DIR from mapped account profile after normal account context policy resolution
• Invalid/missing mapped accounts are skipped safely

User Workflows

New account with shared context

ccs auth create work2 --share-context
ccs auth create backup --context-group sprint-a
ccs auth create backup2 --context-group sprint-a --deeper-continuity

Existing account

• Open ccs config
• Go to Accounts
• Click the pencil icon (Edit History Sync)
• Choose isolated or shared, set group, and (optionally) choose deeper continuity

No account recreation required for this workflow.

Current Limitations

• Shared context is local filesystem sharing. It does not bypass remote provider permission models.
• Session continuity still depends on what the upstream tool/provider stores and allows.
• Context sharing should only be enabled for accounts you intentionally trust to share workspace history.

Alternative: CLIProxy Claude Pool

For users who prefer lower manual account switching, use CLIProxy Claude pool instead:

• Authenticate pool accounts via ccs cliproxy auth claude
• Manage account pool behavior in ccs config -> CLIProxy Plus

Validation Checklist

• Confirm account row shows shared (<group>) in Dashboard Accounts table
• Switch between accounts in the same group and verify workspace continuity
• Run ccs doctor if symlink/context health looks inconsistent