> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Concurrent Sessions

> Run multiple Claude instances simultaneously

# Concurrent Sessions

Run multiple Claude CLI instances simultaneously. Different account profiles normally use different Claude config directories, while launching the same profile twice reuses the same directory and shared state.

## Overview

```bash theme={null}
# Terminal 1
ccs work "implement feature X"

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

# Different profiles = separate default state
```

## Architecture

CCS uses `CLAUDE_CONFIG_DIR` to select the Claude config directory for each account profile:

```
~/.ccs/instances/work/        # Work account
~/.ccs/instances/personal/    # Personal account
```

When you run `ccs work "task"`:

1. Sets `CLAUDE_CONFIG_DIR=~/.ccs/instances/work/`
2. Claude loads credentials from that directory
3. That session reuses the `work` profile's state directory

That gives you a simple rule of thumb:

* Different profiles such as `work` and `personal` normally use different directories
* The same profile such as `work` + `work` reuses one directory
* If you configure continuity inheritance, different profile names can intentionally reuse the same directory too

## Instance Structure

Each account profile gets its own default directory:

```
~/.ccs/instances/work/
├── .anthropic/           # Claude-managed metadata
├── session-env/           # Chat history
├── todos/                 # Task lists
├── logs/                  # Execution logs
├── file-history/          # Recent file context
├── shell-snapshots/       # Shell continuity artifacts
├── debug/                 # Debug artifacts
├── commands/              # Shared link/copy in non-bare profiles
└── skills/                # Shared link/copy in non-bare profiles
```

## Performance

| Metric     | First Use                | Subsequent |
| ---------- | ------------------------ | ---------- |
| Activation | \~20-35ms                | \~5-10ms   |
| Memory     | \~3-5 KB per activation  | -          |
| Disk       | \~200-700 KB per profile | -          |

## Limitations

<Warning>
  Running the **same profile** in multiple terminals is allowed, but both terminals reuse the same `CLAUDE_CONFIG_DIR` and shared state. Use different profiles when you want stronger separation.
</Warning>

```bash theme={null}
# Shared state on purpose:
ccs work "task1"  # Terminal 1
ccs work "task2"  # Terminal 2 - same profile, same state directory

# Separate state:
ccs work "task1"      # Terminal 1
ccs personal "task2"  # Terminal 2
```

<Note>
  This is not a special CCS-only restriction. Any two launches that point at the same Claude config directory share mutable state.
</Note>

### Other Limitations

* `CLAUDE_CONFIG_DIR` is undocumented (keep Claude CLI updated)
* Same-profile launches share history, todos, logs, and other mutable artifacts
* Non-bare profiles share commands, skills, agents, plugins, and `settings.json` via `~/.ccs/shared/`
* Sessions/logs accumulate (manual cleanup if needed)

## Shared Resources

By default, non-bare account profiles reuse the shared CCS layout for commands, skills, agents, plugins, and `settings.json`.

```bash theme={null}
# Recreate shared symlinks after changing shared resources
ccs sync
```

If you created a profile with `--bare`, it opts out of that shared layout on purpose.

## Cleanup

```bash theme={null}
# Check sizes
du -sh ~/.ccs/instances/*

# Clear sessions
rm -rf ~/.ccs/instances/work/session-env/*

# Clear logs
rm -rf ~/.ccs/instances/work/logs/*
```