Hero Dev Tools - Developer Session Manager

A Rust CLI tool for managing developer sessions with btrfs snapshots, enabling isolated Claude coding environments.

Overview

Hero Dev Tools manages developer sessions where each session gets a btrfs snapshot of /code, allowing developers to make changes in isolation. Sessions are tied to system users named dev_${name}.

System Requirements

• Ubuntu Linux
• sudo privileges
• The following packages (auto-installed by herodev init):
  • git
  • buildah
  • podman
  • btrfs-progs

Installation

cargo build -p hero_dev_tools --release
# Binary will be at target/release/hero-dev-tools

Quick Start

Run init to check and install all dependencies:

# Interactive mode - will prompt before installing
hero-dev-tools init

# Force mode - automatically install everything without prompts
hero-dev-tools -f init

# Specify btrfs image size (default: 50GB)
hero-dev-tools init --size 100

Usage

Global Options

-f, --force    Force mode - automatically install/configure without prompts

Commands

# System setup and checks
hero-dev-tools init                              # Check system, prompt to install missing deps
hero-dev-tools -f init                           # Force install all missing deps without prompts
hero-dev-tools init --size 100                   # Use 100GB for btrfs image

# Session management
hero-dev-tools sessions list                     # List all dev sessions
hero-dev-tools sessions create <name>            # Create a new session
hero-dev-tools sessions delete <name>            # Delete a session
hero-dev-tools sessions enter <name>             # Enter session with shell
hero-dev-tools sessions enter <name> --repo <path>        # Enter at specific repo
hero-dev-tools sessions enter <name> --repo <path> --claude  # Enter with Claude Code

# Repository management
hero-dev-tools repos list                        # List git repos in /code
hero-dev-tools repos list --path /some/dir       # List repos in specific directory
hero-dev-tools repos reorganize                  # Reorganize repos to match remote URL structure
hero-dev-tools repos reorganize --path /some/dir

# Changes management
hero-dev-tools changes list <session>            # View changes in a session
hero-dev-tools changes push <session> --all -m "commit message"  # Push all changes

Interactive Mode

Launch the interactive TUI menu:

hero-dev-tools

Init Process

The hero-dev-tools init command performs the following:

1. System Checks

   • Verifies Ubuntu Linux
   • Verifies sudo access
   • Checks for required packages (git, buildah, podman, btrfs-progs)
   • Checks if /code is a btrfs subvolume

2. Package Installation (if missing)

   • Runs apt-get update
   • Installs missing packages

3. Btrfs Setup (if /code not configured)

   • Creates a loopback btrfs image at /var/lib/btrfs-code.img
   • Formats as btrfs filesystem
   • Creates root subvolume
   • Mounts at /code
   • Adds entry to /etc/fstab for persistence

Directory Conventions

/code/                          # Root btrfs subvolume
├── .sessions/                  # Session snapshots
│   └── dev_<name>/            # Individual session snapshot
├── ${serverhostname}/          # Server hostname (regular directory)
│   ├── ${orgname}/             # Organization (regular directory)
│   │   └── ${reponame}/        # Git repository (regular directory)

How It Works

1. Session Creation: Creates a new Linux user dev_<name> and a btrfs snapshot of /code at /code/.sessions/dev_<name>

2. Isolation: Each session has its own copy of the codebase via copy-on-write btrfs snapshots

3. Mount Namespace: When entering a session, HeroDev uses Linux mount namespaces to bind-mount the session's snapshot to /code. This means inside the session, /code shows the session's isolated copy while the rest of the system sees the original /code

4. Changes Tracking: HeroDev can scan for git repositories with uncommitted changes within a session

5. Push Changes: Commit and push changes from session repos back to their remotes

6. Repository Reorganization: Move repositories to follow the /code/{server}/{org}/{repo} convention based on their git remote URLs

Features

• Automatic Setup: hero-dev-tools init installs all dependencies and configures btrfs
• Force Mode: Use -f flag to skip all prompts for scripted deployments
• System Checks: Verify Ubuntu, btrfs, sudo, git, buildah, podman availability
• Session CRUD: Create, list, enter, and delete developer sessions
• Git Integration: Scan repos, detect changes, commit and push
• Repository Reorganization: Auto-organize repos by remote URL structure
• Interactive TUI: Menu-driven interface with colored output
• CLI Interface: Scriptable commands for automation

License

Apache-2.0