claude-env 0.1.0

Claude environment manager - switch between Claude Code configurations

cenv - Claude Environment Manager

Manage isolated Claude Code configurations like pyenv manages Python versions. Switch between different Claude setups (work, personal, experiments) with complete isolation.

Installation

# Install from PyPI (recommended)
pip install claude-env

# Or using uvx (no installation required)
uvx claude-env --help

# Or install from source with uv (for development)
git clone https://github.com/vtemian/claude-env.git
cd claude-env
uv pip install -e .

# Or using pip
pip install -e .

Quick Start

# Initialize cenv (migrates your current ~/.claude to default environment)
cenv init

# Create a new environment for work
cenv create work

# Switch to work environment
cenv use work

# List all environments (* marks active)
cenv list

# Show current environment
cenv current

# Delete an environment
cenv delete work

Features

• Complete Isolation: Each environment has its own CLAUDE.md, settings.json, agents, plugins
• Symlink-based: Fast switching with no data copying
• Safety Checks: Warns when Claude is running
• GitHub Templates: Clone environment configs from repositories
• Shared Credentials: API keys stored in macOS Keychain work across all environments

Configuration

cenv can be configured via environment variables or a config file.

Config File

Create ~/.cenvrc:

# Git operation timeout in seconds (default: 300)
git_timeout = 600

# Logging level (default: INFO)
log_level = DEBUG

Environment Variables

export CENV_GIT_TIMEOUT=600
export CENV_LOG_LEVEL=DEBUG

Configuration Precedence

1. Environment variables (highest priority)
2. ~/.cenvrc file
3. Built-in defaults (lowest priority)

Available Options

• CENV_GIT_TIMEOUT / git_timeout: Git operation timeout in seconds (default: 300)
• CENV_LOG_LEVEL / log_level: Logging level - DEBUG, INFO, WARNING, ERROR, CRITICAL (default: INFO)

Commands

cenv init

Initialize cenv by migrating your existing ~/.claude to ~/.claude-envs/default/.

cenv init

cenv create <name>

Create a new environment. By default, copies from the default environment.

# Create from default
cenv create work

# Create from GitHub repository
cenv create work --from-repo https://github.com/user/claude-work-setup

cenv use <name>

Switch to a different environment. Prompts for confirmation if Claude is running.

cenv use work

# Force switch without confirmation
cenv use work --force

cenv list

List all available environments. Active environment is marked with →.

cenv list

cenv current

Show the currently active environment.

cenv current

cenv delete <name>

Delete an environment. Cannot delete the default environment or currently active environment.

cenv delete work

# Skip confirmation
cenv delete work --force

How It Works

cenv uses symlinks for fast, efficient environment switching:

~/.claude              → symlink to active environment
~/.claude-envs/
  ├── default/         Your original setup
  ├── work/            Work configuration
  └── personal/        Personal configuration

Each environment contains:

• CLAUDE.md - Global instructions
• settings.json - Settings and preferences
• agents/ - Custom agents
• plugins/ - Installed plugins
• history.jsonl, sessions/, etc.

Use Cases

Work vs Personal: Separate configurations for professional and personal use

cenv create work
cenv create personal

Experimentation: Test new plugins or settings without affecting your main setup

cenv create experiment
# Try new things...
cenv delete experiment

Team Templates: Share environment configs via GitHub

cenv create work --from-repo https://github.com/company/claude-work-template

Security

• Git clone operations use shallow clones (--depth 1) and have a 5-minute timeout
• All operations use custom exception types for better error handling
• Comprehensive logging available with --verbose flag
• See SECURITY.md for security considerations

Logging

Enable verbose logging:

cenv --verbose list

Write logs to file:

cenv --log-file ~/cenv.log list

Trash and Recovery

Deleted environments are moved to trash instead of permanently deleted:

# Delete an environment (moves to trash)
cenv delete myenv

# List deleted environments
cenv trash

# Restore from trash
cenv restore myenv-20251111-143022

Development

# Install with dev dependencies
make install

# Run tests (fast)
make test

# Run tests with coverage
make test-cov

# Run type checking (strict)
make typecheck

# Run linting
make lint

# Auto-fix linting issues
make format

# Run all checks (lint + typecheck + test-cov)
make check

# Clean build artifacts
make clean

License

MIT