# 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
```bash
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:
```bash
# 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
```bash
-f, --force Force mode - automatically install/configure without prompts
```
### Commands
```bash
# 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:
```bash
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