repolab

README

repolab

Spin up isolated multi-repo lab environments for AI-assisted development.

What it does

repolab creates named "lab" directories that check out multiple git repos as worktrees side-by-side. Each lab is populated with a template — an AGENTS.md describing the repos, scratch directories, and any other files your AI assistant needs to orient itself. Labs can be listed and torn down cleanly, removing worktrees and branches without touching your main branches.

Installation

go install github.com/bdunn313/repolab@latest

Or build from source:

git clone https://github.com/bdunn313/repolab
cd repolab
go build -o repolab .

To update to the latest version, re-run the same go install command — it always fetches and builds the current @latest release:

go install github.com/bdunn313/repolab@latest

Quick start

# 1. Run first-time setup (sets labs dir, registers your repos)
repolab init

# 2. See available templates
repolab template list

# 3. Preview a template's AGENTS.md
repolab template preview multi-repo

# 4. Create a lab
repolab create my-feature

# 5. See all labs
repolab list

# 6. Tear down when done (removes worktrees, branches, and lab dir)
repolab teardown my-feature

Commands

Setup

Command	Description
repolab --version	Print the installed version
repolab init	Interactive first-run setup

Lab management

Command	Description
repolab create <name>	Create a new lab from a template
repolab list	List all existing labs
repolab teardown <name>	Remove a lab and its worktrees
repolab teardown --force <name>	Teardown without safety checks
repolab repos <name>	List repos in a lab
repolab add-repo <name>	Add a repo to an existing lab
repolab remove-repo <name>	Remove a repo from an existing lab

Template management

Command	Description
repolab template list	List available templates
repolab template preview <name>	Preview a template's AGENTS.md
repolab template new <name>	Scaffold a new custom template
repolab template new --base ab-test <name>	Scaffold from a specific base template

Config management

Command	Description
repolab config show	Print current config
repolab config set <key> <value>	Set a config value (labs_dir, templates_dir)
repolab config repo list	List registered repos
repolab config repo add <path>	Register a repo
repolab config repo remove	Interactively remove a registered repo
repolab config repo-dir add <path>	Register a watched directory (immediate git-repo children are discovered live)
repolab config repo-dir list	List watched directories, with discovered repo counts
repolab config repo-dir remove	Interactively remove a watched directory

Templates

Templates are directories containing a .repolab.tpl.yml metadata file and any other files to be rendered into the lab. Files are processed through Go's text/template engine with these variables:

Variable	Description
{{.LabName}}	The lab name
{{.Date}}	ISO 8601 creation date
{{.Repos}}	Slice of repos (single-env mode), each with .Name, .Path, .WorktreePath, .Branch
{{.Environments}}	Slice of environments (A/B mode), each with .Name and .Repos

Built-in templates

multi-repo (default) — creates an AGENTS.md describing all repos and their worktree locations, plus scratch directories for notes and analysis. Good for feature work, code review, and cross-repo refactoring.

ab-test — creates two isolated environments (env-a and env-b) with separate worktrees per repo, designed for running competing AI agents against the same codebase. Includes:

• scripts/run-agents.sh — runs the same prompt against both environments in parallel (headless with log capture, or interactive via tmux)
• scripts/diff-envs.sh — unified diff of changes in each environment
• scripts/compare-logs.sh — side-by-side commit history comparison
• scripts/compare-tests.sh — runs a test command in both environments and diffs output
• scripts/summarize.ts — calls the Claude API to produce a structured markdown judgment comparing both environments (requires Bun and ANTHROPIC_API_KEY)
• mise.toml — pre-configured tasks for all of the above

Creating custom templates

The fastest way to create a custom template:

# Scaffold from the default multi-repo template
repolab template new my-template

# Or scaffold from ab-test
repolab template new --base ab-test my-template

This copies the base template into your templates_dir, opens .repolab.tpl.yml in $EDITOR, and you're ready to customize. If templates_dir isn't set, the command prompts you to configure it.

To create a template manually:

1. Create a directory (e.g., ~/.config/repolab/templates/my-template/)
2. Add a .repolab.tpl.yml metadata file (see below)
3. Add any files you want rendered into new labs
4. Set templates_dir in your config to point to the parent directory

Template metadata (.repolab.tpl.yml)

name: my-template
description: What this template is for
worktree_dir: repos              # where repo worktrees are placed (relative to lab dir)
extends: multi-repo              # optional: inherit files from another template

All fields:

Field	Required	Description
name	yes	Template identifier
description	yes	Human-readable description
worktree_dir	yes*	Directory for repo worktrees, relative to lab dir
extends	no	Name of a base template to inherit files from (no chaining)
environments	no	List of environments for A/B-style templates (replaces worktree_dir)

*Required unless environments is set.

Template inheritance: When extends is set, files from the base template are rendered first, then files from the child template overlay on top. This lets you customize just an AGENTS.md or add scripts without duplicating the entire base. Chained inheritance (a base that also extends another) is not supported.

Templates no longer support post_init. Keep setup scripts in your template and run them manually after repolab create once you've reviewed the generated files.

Multi-environment templates: Replace worktree_dir with environments to create multiple isolated worktree sets:

environments:
  - name: a
    worktree_dir: env-a/repos
  - name: b
    worktree_dir: env-b/repos

In environment mode, use {{.Environments}} instead of {{.Repos}} in your template files. Each environment has .Name (string) and .Repos (same fields as single-env repos).

See docs/templates.md for the full template authoring reference.

Teardown safety

repolab teardown and repolab remove-repo check each worktree for potential data loss before removing it:

• Uncommitted changes
• Branch never pushed to a remote
• Commits not yet merged into the default branch
• Commits on the remote not yet pulled locally

When any of these conditions are detected, the command displays a per-repo warning and prompts for confirmation before proceeding. Pass --force / -f to skip all checks.

If a worktree removal fails, the lab's state file (.repolab.yml) is preserved so you can investigate and retry.

Configuration

Config lives at ~/.config/repolab/config.toml:

labs_dir = "~/Labs"       # where labs are created
templates_dir = ""         # path to custom templates dir; empty = embedded only

[[repos]]
path = "/Users/you/Code/repo-a"

[[repos]]
path = "/Users/you/Code/repo-b"

repo_dirs = ["/Users/you/Code"]  # watched dirs; immediate git-repo children are discovered live

Run repolab init to configure this interactively, or use repolab config set, repolab config repo add, and repolab config repo-dir add to update individual values.

Design

See SPEC.md for design rationale and goals.