jolt

A CLI tool for managing multiple Git worktrees across repositories for feature development with Claude Code.

Features

• Multi-repo feature management: Work on features that span multiple repositories
• Git worktrees: Use Git worktrees for parallel development without branch switching
• Automatic file copying: Copy files like .env to worktrees
• Symlink support: Create symlinks for node_modules or other shared directories
• Post-create hooks: Run commands after creating worktrees (e.g., npm install)
• Pre-delete hooks: Run cleanup commands before deleting worktrees
• Terminal integration: Automatically open a terminal in the new worktree

Installation

npm install -g jolt-cli

Or install locally:

npm install
npm run build
npm link

Quick Start

# Initialize jolt in your project directory
cd ~/projects/my-app
jolt init

# List discovered repositories
jolt repos

# Create a new feature (default aspect)
jolt new user-auth --repos api,web

# Or with a named aspect
jolt new user-auth backend --repos api,worker

# Or create with all repos
jolt new user-auth --all

# List active features
jolt list

# Check feature status (auto-detects from cwd)
cd .jolt/worktrees/user-auth/default/api
jolt status

# Pull latest from feature branch into worktree
jolt pull

# Push worktree changes to feature branch
jolt push

# Push and cleanup worktrees
jolt push --delete

# Delete a feature
jolt delete user-auth

Exit Codes

jolt follows standard Unix conventions for exit codes:

• 0 - Success
• 1 - User error (invalid input, feature not found, etc.)
• 2 - System error (git failure, file system error, etc.)

This allows you to check command status in scripts:

if jolt new my-feature --all; then
  echo "Feature created successfully"
else
  echo "Failed with exit code: $?"
fi

Configuration

Global Config: ~/.jolt/config.toml

[terminal]
open = "auto"                    # "auto" | "none"
# command = "wezterm start --cwd {path}"   # Custom terminal command

[defaults]
open_terminal = true             # Open terminal after creating feature
fetch_before_branch = true       # Fetch before creating branch

Repository Config: <repo>/jolt.config.toml

base_branch = "main"             # Base branch (auto-detected if not set)

copy = [                         # Files/directories to copy
    ".env",
    ".env.*.local",
    ".idea",
]

symlink = [                      # Files/directories to symlink
    "node_modules",
]

[hooks]
post_create = ["npm install"]    # Commands to run after creating worktree
pre_delete = []                  # Commands to run before deleting worktree

Commands

Commands have different location requirements:

Location	Commands
Home directory only	new, delete, repos, list
Worktree only	pull, push
Anywhere in jolt home	init, status, include, open, config

---

Home Directory Commands

These commands manage features and repositories. Run them from the jolt home directory (where .jolt/ lives).

jolt new <feature-name> [aspect-name]

Create a new feature with worktrees across selected repositories. Aspect name defaults to "default" if not specified.

# Create feature with default aspect
jolt new user-auth --repos api,web

# Create feature with named aspect
jolt new user-auth backend --repos api,worker

# All repositories
jolt new user-auth --all

# Don't open terminal
jolt new user-auth --all --no-open

jolt delete <feature-name>

Delete a feature and its worktrees.

# Delete with confirmation
jolt delete user-auth

# Delete without confirmation
jolt delete user-auth --yes

# Force delete even with uncommitted changes
jolt delete user-auth --force

jolt repos

List all discovered Git repositories in the home directory.

jolt repos

jolt list

List all active features with their repositories and creation time.

jolt list

---

Worktree Commands

These commands sync changes between worktrees and feature branches. Run them from within a worktree.

jolt pull

Rebase worktree onto the feature branch. Use this to get changes from teammates who pushed to the feature branch.

cd .jolt/worktrees/user-auth/default/api
jolt pull

jolt push

Update feature branch from worktree. Use this to share your worktree changes with teammates.

# Push worktree changes to feature branch
jolt push

# Push and delete worktrees
jolt push --delete

# Force push even with uncommitted changes
jolt push --force

---

Context-Aware Commands

These commands can be run from anywhere within the jolt home directory. They auto-detect context from your current working directory.

jolt init

Initialize jolt in the current directory. Creates .jolt/ directory and discovers Git repositories.

jolt init

jolt status [feature-name] [aspect-name]

Show the status of a feature's worktrees. Auto-detects feature from current working directory if not specified.

# From within a worktree (auto-detects)
cd .jolt/worktrees/user-auth/default/api
jolt status

# Or specify feature name
jolt status user-auth

jolt include [repos...]

Include additional repositories in an existing feature aspect. Auto-detects feature and aspect from cwd.

# From within a worktree (auto-detects feature/aspect)
jolt include another-repo

# Or specify feature explicitly
jolt include another-repo --feature user-auth

jolt open [feature-name] [aspect-name] [repo]

Open a terminal in a feature's worktree.

# Open terminal in feature directory (auto-detects feature from cwd)
jolt open

# Open terminal in specific feature
jolt open user-auth

# Open terminal in specific repo worktree
jolt open user-auth default api

# Open in editor instead of terminal
jolt open user-auth --editor

If the terminal cannot be opened, the path is printed for manual navigation.

jolt config <type>

Open a config file in your editor. Type can be home, global, or repo.

jolt config home    # Edit home-specific config
jolt config global  # Edit global config
jolt config repo    # Edit repository config (run from within a repo)

Project Structure

home/
├── repo-a/                     # Root repository
│   ├── .git/
│   ├── jolt.config.toml       # Repo-specific config
│   └── .env
├── repo-b/
│   ├── .git/
│   └── jolt.config.toml
└── .jolt/                      # jolt state
    ├── features.toml           # Active features registry
    ├── home.toml               # Home-specific config (optional)
    └── worktrees/              # Feature worktrees
        └── feature-a/
            ├── aspect-a
            │   ├── repo-a/         # Worktree for repo-a
            │   └── repo-b/         # Worktree for repo-b
            └── aspect-b
                ├── repo-a/         # Worktree for repo-a
                └── repo-b/         # Worktree for repo-b

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run lint

# Watch mode
npm run dev

License

MIT