ContextSwitch

Manage domain-based contexts for Claude Code CLI. Switch between projects without losing session history -- each domain remembers where you left off via Claude's --resume flag.

Stop burning tokens on context reconstruction. Every time you start a fresh Claude session on an existing project, you pay a tax: Claude re-reads your files, you re-explain your conventions, and thousands of tokens are spent before any productive work begins. ContextSwitch eliminates this by persisting sessions across project switches.

Installation

Prerequisites: Node.js 18 or later, Claude Code CLI

npm install -g contextswitch

This installs the cs command globally.

Quick Start

# Initialize ContextSwitch (creates a default domain)
cs init

# Create domains for your projects
cs domain add backend --working-dir ~/projects/api --description "Backend API"
cs domain add frontend --working-dir ~/projects/web --description "React frontend"

# Switch to a domain (launches Claude in that project's directory)
cs switch backend

# Later, switch to frontend (backend session is preserved)
cs switch frontend

# Switch back -- Claude resumes exactly where you left off
cs switch backend

Commands

Core

| Command | Description | |---|---| | cs init | Initialize ContextSwitch and create a default domain | | cs switch <domain> | Switch to a domain (launches Claude with the domain's config) | | cs list | List all domains (ls also works) | | cs status [domain] | Show session info, age, and risk level |

switch options:

cs switch backend                    # Resume existing session
cs switch backend --force            # Force a brand-new session
cs switch backend --mode window      # Open in a new terminal window (default)
cs switch backend --mode tab         # Open in a new tab
cs switch backend --mode inline      # Run in the current terminal

If the domain is already active but Claude has exited, cs switch automatically relaunches -- no need to switch away and back.

Launch Modes

ContextSwitch supports three modes for opening Claude:

| Mode | Description | |---|---| | window | Opens Claude in a new terminal window (default) | | tab | Opens Claude in a new tab (macOS Terminal, Windows Terminal, gnome-terminal) | | inline | Runs Claude directly in the current terminal (useful for SSH / remote dev) |

Launch mode can be set:

1. Per command: cs switch backend --mode tab
2. Per domain: launchMode: tab in domain YAML
3. Globally: defaultLaunchMode: tab in global config
4. Default: window

Domain Management

| Command | Description | |---|---| | cs domain add <name> | Create a new domain | | cs domain remove <name> | Delete a domain (prompts for confirmation) | | cs domains | Alias for cs domain (works with add, remove, etc.) | | cs reset <domain> | Archive and reset a domain's session | | cs archive <domain> | Snapshot the current session without resetting |

domain add options:

# Basic usage (current directory if --working-dir is omitted)
cs domain add backend --working-dir ~/projects/api

# With description
cs domain add frontend -w ~/projects/app --description "React frontend"

# Inherit settings from another domain
cs domain add staging --extends backend

# Windows
cs domain add backend --working-dir C:\Users\you\projects\api

reset options:

cs reset backend                # Archive current session, then reset
cs reset backend --skip-archive # Reset without archiving
cs reset backend --force        # Skip confirmation prompt

Diagnostics

| Command | Description | |---|---| | cs doctor | Check Claude CLI installation, config, and running processes | | cs --verbose switch backend | Enable debug logging (or set CS_DEBUG=1) | | cs --help | Show help | | cs --version | Show version |

Domain Configuration

Domains are YAML files in the config directory. You can edit them directly after creating with cs domain add:

name: backend
workingDirectory: ~/projects/api
launchMode: tab

metadata:
  description: Backend API project

# Environment variables available to Claude's shell
env:
  NODE_ENV: development
  DATABASE_URL: postgresql://localhost:5432/myapp

# MCP servers registered when this domain is active
mcpServers:
  postgres:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-postgres"]
    env:
      POSTGRES_CONNECTION: postgresql://localhost:5432/myapp

# Memory files symlinked into Claude's memory directory
memoryFiles:
  - ~/projects/api/docs/architecture.md
  - ~/projects/api/docs/conventions.md

# Inherit from another domain
extends: base-api

What Each Field Does

| Field | Description | |---|---| | workingDirectory | Claude opens in this directory when you switch to the domain | | launchMode | Default launch mode for this domain (window, tab, or inline) | | env | Environment variables injected into Claude's shell session | | mcpServers | MCP servers merged into Claude's config on switch (preserves your other servers) | | memoryFiles | Files symlinked into Claude's memory directory for domain-specific context | | extends | Inherit configuration from a parent domain |

Platform Support

| Platform | Status | Notes | |---|---|---| | macOS | Fully supported | Terminal.app windows and tabs via AppleScript | | Linux | Fully supported | gnome-terminal, xterm, konsole, xfce4-terminal | | Windows | Fully supported | Windows Terminal (with tabs), PowerShell, Git Bash |

Windows details:

• Launch scripts are automatically converted from bash to PowerShell
• Windows Terminal (wt.exe) is used when available for native tab support
• Falls back gracefully to PowerShell via cmd start, then Git Bash
• Correctly distinguishes between Claude desktop GUI and Claude Code CLI
• If tabs are requested without Windows Terminal, displays an install link

Config and state location:

• macOS: ~/Library/Application Support/contextswitch/
• Linux: ~/.config/contextswitch/
• Windows: %APPDATA%\contextswitch\

How It Works

Domains are named project contexts. Each has a working directory, environment variables, MCP servers, memory files, and a persistent session. Domain config is human-readable YAML.

Sessions are Claude conversations identified by a UUID. When you run cs switch, ContextSwitch retrieves (or creates) a session ID for that domain and launches Claude with --resume <sessionId>. Claude picks up where the previous conversation left off. If resume fails, it automatically falls back to a new session.

MCP config is updated on each switch. Domain-specific MCP servers are merged into your existing Claude config -- your other servers are preserved.

Memory files are symlinked into Claude's memory directory when you switch. Edits to the source files are reflected automatically without re-switching.

Smart relaunch detects when a domain is marked active but Claude has exited. Instead of blocking with "already active", it relaunches the session automatically.

Token Savings

Every cold start costs tokens -- Claude re-reads your project, you re-explain conventions, and the AI rebuilds its internal model. On a moderately complex project, this costs 5,000-20,000 tokens per switch.

With ContextSwitch, resumed sessions skip this entirely. For a developer switching between three projects a few times a day, that's 30,000-50,000 tokens saved daily. Over a month, that's over 600,000 tokens that go toward writing code instead of rebuilding context.

Resumed sessions also produce better output -- Claude remembers your architecture, follows established conventions, and doesn't repeat mistakes from earlier in the conversation.

Changelog

See CHANGELOG.md for a full version history.

License

MIT