ccenv

Claude Code Environment Manager. ccenv lets you swap logical working states in a single Git checkout without worktrees.

Requirements

• Bun v1.1+
• Git
• tar

Install

curl -fsSL https://raw.githubusercontent.com/masudahiroto/ccenv/main/install.sh | bash

Or manually clone the repo and run via Bun:

bun ./src/ccenv.ts --help

Optional: add a shell alias:

alias ccenv="bun /path/to/ccenv/src/ccenv.ts"

Usage

Create and use an environment:

ccenv create feature-a
ccenv enter feature-a
# ...make changes...
ccenv exit

Activate for convenience:

eval "$(ccenv activate feature-a)"
ccenv enter

Run a one-off command inside an environment:

ccenv run --env feature-a -- sh -c "echo hello > example.txt"

Apply environment changes onto the current workspace:

ccenv apply feature-a

Check system status:

ccenv status

Update ccenv to the latest version:

ccenv update

AI Agent Integration

ccenv can automatically manage environments for AI agents to prevent them from conflicting with your manual work or each other.

Google Gemini CLI

Install hooks for gemini-cli:

ccenv install gemini-cli

This configures .gemini/settings.json to automatically enter the active environment before tools run and exit afterwards.

Claude Code

Install hooks for claude-code:

ccenv install claude-code

This configures .claude/settings.json to ensure Claude works safely within the ccenv managed environment.

How it works

ccenv snapshots Git state into .ccenv/envs/<name>:

• staged.patch for staged changes
• unstaged.patch for unstaged changes
• untracked.tar.gz for untracked files
• info.json for metadata

enter stores the current workspace as default, cleans the tree, and restores the target env.
exit saves the env, cleans the tree, and restores default.

Tests

bun test

Notes

• .ccenv/ is untracked by default. Avoid storing other data inside it.