Swarm - Git Worktree + Tmux Session Manager

Seamless parallel development with Git worktrees and dedicated tmux sessions

Swarm manages Git worktrees with dedicated tmux sessions, designed for workflows that require multiple parallel branches within the amplifier/ai_working/ directory structure.

Quick Start

# Build
make install

# Launch interactive TUI (default)
swarm

# Or use CLI commands directly:

# Create a new worktree
swarm create my-project feature/new-feature --from main

# Open in tmux session
swarm open my-project feature/new-feature

# List all worktrees
swarm list --all

# Remove when done
swarm remove my-project feature/new-feature

Features

✨ Core Features:

🌳 Git worktree lifecycle management (create, list, remove, prune)
💻 Automatic tmux session creation and attachment
🎨 Interactive TUI for browsing and managing worktrees (default interface)
🔍 Repository discovery across ai_working/
🛡️ Safety checks before removal (uncommitted changes, unpushed commits)
💾 State persistence with reconciliation
⚙️ Configurable directory patterns and defaults
🎯 Session management (kill sessions without removing worktrees)

🚀 Coming Soon (Phase 2-3):

🔄 Session restoration (revive command)
🪝 Extensibility hooks for custom workflows
📊 Health checks and orphan detection

Why Swarm?

Working on multiple features simultaneously requires juggling Git branches and development contexts. Swarm automates:

Worktree Management - No more manual git worktree add commands
Tmux Integration - Each worktree gets its own session with custom layout
Context Switching - Instant switching between features
Safety - Prevents accidental data loss with pre-removal checks
Discoverability - All worktrees visible to AI tools in ai_working/

Installation

Prerequisites

Go 1.21+ (install)
Git 2.31+ with worktree support
tmux 3.0+
macOS or Linux

Build from Source

cd ai_working/swarm
go mod download
go build -o swarm ./cmd/swarm
sudo cp swarm /usr/local/bin/

Or use the Makefile:

make install

Configuration

Swarm uses layered configuration with the following precedence:

Environment variables (highest priority)
User config (~/.config/swarm/config.yml)
Project config ($AI_WORKING_DIR/.swarmrc)
Built-in defaults

Example config.yml

# Location of repositories (default: ~/amplifier/ai_working)
ai_working_dir: ~/amplifier/ai_working

# Default base branch for new worktrees
default_base_branch: main

# Worktree directory pattern (patternA, patternB, patternC)
# patternA: ai_working/repo__wt__slug (recommended)
# patternB: ai_working/repo.worktrees/slug
# patternC: ai_working/repo/.swarm/worktrees/slug
worktree_pattern: patternA

# Create tmux session when creating worktree
create_session_on_create: true

# Custom tmux layout script (optional)
tmux_layout_script: ~/.config/swarm/layout.sh

# Status cache TTL (for expensive git operations)
status_cache_ttl: 30s

# Auto-prune git after removing worktree
auto_prune_on_remove: true

Environment Variables

export AI_WORKING_DIR="$HOME/amplifier/ai_working"
export SWARM_DEFAULT_BASE_BRANCH="main"
export SWARM_WORKTREE_PATTERN="patternA"

Usage

Creating Worktrees

# Create from existing branch
swarm create <repo> <branch>

# Create new branch from base
swarm create <repo> <branch> --from main

# Custom slug
swarm create <repo> <branch> --slug custom-slug

# Skip tmux session creation
swarm create <repo> <branch> --no-session

Example:

swarm create my-project feature/payments-refactor --from main
# Created: ai_working/my-project__wt__feature_payments-refactor
# Tmux session: my-project--wt--feature_payments-refactor

Opening Worktrees

# Open (attach to tmux session, create if needed)
swarm open <repo> <branch|slug>

# Only attach to existing session (don't create)
swarm open <repo> <branch> --attach-only

# Create worktree if missing
swarm open <repo> <branch> --create

Example:

swarm open my-project feature/payments-refactor
# Attaches to tmux session
# Inside tmux: window 1 = nvim, window 2 = shell, window 3 = tests

Listing Worktrees

# List worktrees for specific repo
swarm list <repo>

# List all worktrees
swarm list --all

# JSON output
swarm list --all --json

# Filter by repo
swarm list --repo my-project

Example output:

my-project
  ✓ main                     /path/to/my-project
  ✓ feature_payments-refactor /path/to/my-project__wt__feature_payments-refactor
    [MODIFIED] [UNPUSHED]
    Last opened: 2 hours ago

underworld-tf
  ✓ main                     /path/to/underworld-tf

Removing Worktrees

# Remove worktree (with safety checks)
swarm remove <repo> <branch|slug>

# Force remove (bypass safety checks)
swarm remove <repo> <branch> --force

# Keep git branch after removing worktree
swarm remove <repo> <branch> --keep-branch

Safety checks:

⚠️ Uncommitted changes (blocks removal)
⚠️ Unpushed commits (warns but allows)
ℹ️ Branch not merged (info only)

Example:

swarm remove my-project feature/payments-refactor
# ⚠️  Cannot remove worktree:
#   • Worktree has uncommitted changes
#
# View changes: cd /path/to/worktree && git status
# Remove anyway: swarm remove my-project feature/payments-refactor --force

Interactive TUI

The TUI is now the default interface when running swarm without arguments.

# Launch TUI
swarm

# Or explicitly
swarm tui

Features:

Browse all repositories and worktrees in a three-pane layout
Navigate with arrow keys or vim-style (j/k/h/l)
Press Enter to select and view worktree details
Auto-selection: first worktree automatically selected when entering a repo
Open worktrees in tmux sessions directly from the TUI
Remove worktrees with safety checks
View git status badges (modified, unpushed, merged)

Keyboard shortcuts:

↑/↓ or j/k - Navigate
Enter - Select/Open
o - Open worktree in tmux
d - Delete worktree (with confirmation)
c - Copy path/branch name
r - Refresh
q or Ctrl+C - Quit

Session Management

# List all tmux sessions
swarm sessions

# Kill a specific session (preserves worktree)
swarm kill-session <repo> <branch>

Example:

# Kill session but keep the worktree
swarm kill-session my-project feature/payments-refactor
# ✓ Killed tmux session for my-project/feature/payments-refactor
# Worktree preserved at: /path/to/worktree

This is useful for cleaning up sessions without destroying work.

Other Commands

# Prune stale worktree references
swarm prune <repo>
swarm prune --all

# Validate environment
swarm doctor

# Show config
swarm config get <key>
swarm config set <key> <value>

# Get worktree info from path
swarm info /path/to/worktree

Directory Structure

Pattern A (Default - Flat Sibling)

ai_working/
├── my-project/                          # Base repo
├── my-project__wt__main/                # Worktree for main
├── my-project__wt__feature_foo/         # Worktree for feature/foo
├── underworld-tf/
├── underworld-tf__wt__feature_bar/
└── .swarm-state.json                      # State file

Benefits:

First-class visibility for AI tools
Easy to discover and clean up
Simple mental model

Tmux Session Naming

Format: <repo-slug>--wt--<worktree-slug>

Examples:

my-project--wt--main
my-project--wt--feature_payments-refactor
underworld-tf--wt--bugfix_auth-issue

Architecture

Swarm follows the "bricks and studs" modular design philosophy:

┌─────────────────────────────────────────┐
│           CLI Layer (Cobra)             │
│    create, open, list, remove, etc.     │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│         Domain Modules                  │
│  • repo_discovery                       │
│  • worktree_manager                     │
│  • tmux_manager                         │
│  • state_store                          │
│  • config                               │
│  • safety_checker                       │
└─────────────────┬───────────────────────┘
                  │
┌─────────────────▼───────────────────────┐
│      Infrastructure (Git, Tmux)         │
└─────────────────────────────────────────┘

Each module is:

Self-contained with clear boundaries
Regeneratable from specifications
Testable in isolation

See docs/ARCHITECTURE.md for details.

Development

Project Structure

swarm/
├── cmd/swarm/          # CLI entry point
├── internal/
│   ├── config/         # Configuration loading
│   ├── git/            # Git command wrapper
│   ├── state/          # State persistence
│   ├── repo/           # Repository discovery
│   ├── worktree/       # Worktree lifecycle
│   ├── tmux/           # Tmux session management
│   └── safety/         # Safety checks
├── docs/
│   ├── ARCHITECTURE.md # System architecture
│   ├── DECISIONS.md    # Architecture decision records
│   ├── MODULES.md      # Module specifications
│   └── plans/          # Implementation plans
└── test/
    ├── fixtures/       # Test data
    └── integration/    # Integration tests

Running Tests

# Unit tests
go test ./internal/... -v

# Integration tests (requires git + tmux)
go test ./internal/... -v -tags=integration

# All tests with coverage
go test ./... -v -coverprofile=coverage.out
go tool cover -html=coverage.out

Building

# Development build
go build -o swarm ./cmd/swarm

# Production build (optimized)
go build -ldflags="-s -w" -o swarm ./cmd/swarm

# Multi-platform
GOOS=darwin GOARCH=amd64 go build -o swarm-darwin-amd64
GOOS=darwin GOARCH=arm64 go build -o swarm-darwin-arm64
GOOS=linux GOARCH=amd64 go build -o swarm-linux-amd64

Code Quality

# Format
go fmt ./...

# Lint
golangci-lint run

# Vet
go vet ./...

Implementation Roadmap

✅ Phase 1: Foundation & Core CLI (Current)

Project scaffolding
Config module (loading, precedence, validation)
Git module (worktree commands, parsing)
State module (JSON persistence, locking)
Repo module (discovery, validation)
Worktree module (slug generation, CRUD)
CLI commands: create, list, open, remove
Basic testing

🚧 Phase 2: TUI & Safety (Next)

TUI framework setup (Bubble Tea)
Interactive worktree browser
Safety checks (uncommitted, unpushed, merged)
Tmux session management
Status computation (with caching)
Orphan detection

🎯 Phase 3: Refinement

revive command (restore sessions)
rename command (branch + slug)
Performance optimizations (parallel scanning)
Shell completions (bash, zsh, fish)
Comprehensive error messages
User documentation

🔮 Phase 4: Extensibility

Design Philosophy

Swarm adheres to the Amplifier implementation philosophy:

Ruthless Simplicity - Keep everything as simple as possible
Architectural Integrity - Preserve patterns, simplify implementations
Bricks and Studs - Self-contained modules with stable contracts
Regeneratable Code - Modules can be rebuilt from specifications
Test-First - Every module has comprehensive tests

See ai_context/IMPLEMENTATION_PHILOSOPHY.md for details.

Troubleshooting

Worktree creation fails

# Check git version (need 2.31+)
git --version

# Verify repo is git repository
cd ai_working/repo-name
git status

# Check for existing worktrees
git worktree list

Tmux session not found

# List all sessions
tmux ls

# Check if tmux is running
ps aux | grep tmux

# Manually create session
swarm open repo branch --create

State file corruption

# Backup current state
cp ai_working/.swarm-state.json ai_working/.swarm-state.json.bak

# Regenerate from git
swarm scan --rebuild

Permission errors

# Check directory permissions
ls -la ~/amplifier/ai_working

# Check git worktree permissions
git worktree list

Contributing

Reporting Issues

Check existing issues
Provide minimal reproduction
Include:
- OS and version
- Go version (go version)
- Git version (git --version)
- Tmux version (tmux -V)
- Swarm version (swarm version)
- Error messages and logs

Development Setup

# Clone repo
cd ~/amplifier/ai_working/swarm

# Install dependencies
go mod download

# Run tests
make test

# Build
make build

Pull Requests

Create feature branch
Write tests (aim for >80% coverage)
Update documentation
Run make check (format, lint, test)
Submit PR with description

License

[License to be determined]

Acknowledgments

Inspired by existing tools:

wttw - Git worktree in tmux window
dmux - Worktree + AI agent integration
phantom - Parallel development with worktrees

Built with:

Cobra - CLI framework
Bubble Tea - TUI framework (Phase 2)
Viper - Configuration management

Links

Questions? Open an issue or check the documentation.

Status: Phase 1 (Foundation) - In Development

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
cmd		cmd
docs		docs
internal		internal
.gitignore		.gitignore
Makefile		Makefile
README.md		README.md
go.mod		go.mod
go.sum		go.sum

dannyfuf/swarm

Folders and files

Latest commit

History

Repository files navigation

Swarm - Git Worktree + Tmux Session Manager

Quick Start

Features

Why Swarm?

Installation

Prerequisites

Build from Source

Configuration

Example config.yml

Environment Variables

Usage

Creating Worktrees

Opening Worktrees

Listing Worktrees

Removing Worktrees

Interactive TUI

Session Management

Other Commands

Directory Structure

Pattern A (Default - Flat Sibling)

Tmux Session Naming

Architecture

Development

Project Structure

Running Tests

Building

Code Quality

Implementation Roadmap

✅ Phase 1: Foundation & Core CLI (Current)

🚧 Phase 2: TUI & Safety (Next)

🎯 Phase 3: Refinement

🔮 Phase 4: Extensibility

Design Philosophy

Troubleshooting

Worktree creation fails

Tmux session not found

State file corruption

Permission errors

Contributing

Reporting Issues

Development Setup

Pull Requests

License

Acknowledgments

Links

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages