box

日本語

A CLI tool that manages workspaces via git clone --local. Multi-repo support included.

What is box?

Box creates and manages named workspaces using git clone --local.

• Register repos with box repo add, then create sessions — each session clones repos into ~/.box/workspaces/<session>/
• Multiple repos can be grouped into a single session
• Each clone has its own .git, so the original repo is never affected

Features

• git clone --local workspaces — fast cloning with hardlinks, fully independent .git
• Multi-repo sessions — group multiple repos into one workspace
• Interactive TUI — select repos, enter session name and command, with history
• Shell integration — completions and cd wrapper for zsh/bash

Requirements

• Git

Install

Quick install

curl -fsSL https://raw.githubusercontent.com/yusukeshib/box/main/install.sh | bash

From crates.io

cargo install box-cli

From source

cargo install --git https://github.com/yusukeshib/box

Nix

nix run github:yusukeshib/box

Binary download

Pre-built binaries are available on the GitHub Releases page.

Quick Start

# 1. Register a repo
box repo add ~/projects/my-app

# 2. Create a session via TUI
box

# 3. Or create via CLI
box new my-feature --repo my-app -- make test

# 4. Clean up
box remove my-feature

Usage

box                                    Interactive TUI (create new sessions)
box new <name> --repo <r> [-- cmd...]  Create a new session
box edit <name>                        Add/remove repos in a session
box exec <name> -- <cmd...>            Run a command in a session workspace
box list [options]                     List sessions (alias: ls)
box remove <name>                      Remove a session and its workspace
box cd <name>                          cd into the session workspace
box repo add [path]                    Register a git repo
box repo remove <name>                 Unregister a repo
box repo list                          List registered repos (alias: ls)
box config zsh|bash                    Output shell configuration
box upgrade                            Upgrade to latest version

Create a session

# With a command
box new my-feature --repo my-app -- make test

# Multiple repos
box new my-feature --repo frontend --repo backend

# Minimal
box new my-feature --repo my-app

--repo is required. To create sessions interactively, use box (no arguments) to launch the TUI.

Edit session repos

box edit my-feature             # Add/remove repos in an existing session

List and manage sessions

box list                        # List all sessions
box ls                          # Alias
box list -q                     # Names only (for scripting)
box list -p                     # Only sessions for the current project
box remove my-feature           # Remove session and workspace

Navigate to a workspace

box cd my-feature               # cd into the session workspace

With shell integration enabled (eval "$(box config zsh)"), box cd changes your working directory. Without it, the workspace path is printed to stdout.

Multi-repo Workspaces

Register repos, then reference them by name when creating sessions:

box repo add ~/projects/frontend
box repo add ~/projects/backend

box new my-feature --repo frontend --repo backend

Each repo is cloned into ~/.box/workspaces/<session>/<repo>/. For single-repo sessions, the workspace path resolves directly to the repo subdirectory.

Options

box new

box list

Environment Variables

Shell Integration

# Zsh (~/.zshrc)
eval "$(box config zsh)"

# Bash (~/.bashrc)
eval "$(box config bash)"

This provides tab completions and a box shell function that enables box cd to change your working directory.

How It Works

registered repos      box new my-feature        ~/.box/workspaces/my-feature/
  frontend/      ──── git clone --local ────>      frontend/
  backend/                                         backend/

git clone --local creates an independent git repo using hardlinks for file objects. Each clone has its own .git directory — commits, branches, resets, and destructive operations in the workspace do not affect the original.

Design Decisions

git clone --local is independent (own .git), fast (hardlinks), complete (full history), and simple (no wrapper scripts).

Claude Code Integration

Box works well with Claude Code for running AI agents in independent workspaces:

box new ai-experiment --repo my-app -- claude

Everything the agent does stays in the workspace. Delete the session when done.

License

MIT