ramp

Work on features across multiple repositories simultaneously using git worktrees and automated workflows.

ramp init          # Initialize multi-repo project
ramp up my-feature # Create feature branches across all repos
ramp status        # View all active features
ramp down my-feature # Clean up when done

Why Ramp?

Modern applications span multiple repositories (microservices, frontend/backend, libraries). Ramp automates the entire development workflow:

🚀 One command setup - Create branches across all repos simultaneously
🔄 Git worktrees - Work on multiple features in parallel without branch switching
🎯 Port management - Automatic port allocation prevents conflicts
📦 Environment automation - Custom scripts handle dependencies and services
🧹 Batch cleanup - Remove all merged features with ramp prune

Quick Start

Install

Homebrew (macOS/Linux):

brew install freedomforeversolar/tools/ramp

Pre-built binaries: Download from releases

From source:

git clone https://github.com/FreedomForeverSolar/ramp.git
cd ramp
go build -o ramp .
./install.sh

Auto-Updates

Homebrew installs automatically stay up-to-date 🎉

When installed via Homebrew, ramp automatically updates itself in the background whenever new versions are released. Updates happen silently while you work—you'll always have the latest features and fixes without lifting a finger.

Configuration (~/.ramp/settings.yaml):

auto_update:
  enabled: true      # Set to false to disable
  check_interval: 12h  # How often to check (default: 12h)

The settings file is auto-created on first run. Edit it anytime to customize auto-update behavior.

Manual installs (from source or pre-built binaries) don't auto-update—you'll need to manually pull updates or reinstall when you want to upgrade.

Try the Demo

cd demo/demo-microservices-app
ramp install      # Clone demo repositories
ramp up my-feature # Create feature across all repos
ramp status       # View status
ramp down my-feature # Clean up

Create Your Project

mkdir my-project && cd my-project
ramp init         # Interactive setup
ramp up my-feature # Start coding!

Claude Code Plugin

Ramp ships with a Claude Code plugin that teaches Claude how to work with ramp.yaml configs, setup/cleanup scripts, and worktree-based features.

Install it from inside Claude Code:

/plugin marketplace add FreedomForeverSolar/ramp
/plugin install ramp@ramp

Once installed, the ramp-cli skill activates automatically when you're working in a .ramp/ directory or editing ramp configuration.

Desktop App

Prefer a GUI? The Ramp desktop app provides a visual interface for managing your multi-repo projects with real-time progress updates, one-click feature creation, and custom command execution.

Download for macOS

How It Works

Ramp creates isolated workspaces for each feature using git worktrees:

my-project/
├── .gitignore          # Auto-generated (ignores repos/, trees/, local config)
├── .ramp/
│   └── ramp.yaml       # Configuration
├── repos/              # Main repository clones (gitignored)
│   ├── frontend/
│   └── api/
└── trees/              # Feature workspaces (gitignored, where you work)
    ├── feature-a/
    │   ├── frontend/   # Worktree on branch feature/feature-a
    │   └── api/        # Worktree on branch feature/feature-a
    └── feature-b/
        ├── frontend/
        └── api/

Each feature gets:

Dedicated branches in all repositories
Isolated working directories (git worktrees)
Unique port allocation
Automated setup (install deps, start services, run migrations)
Automated cleanup

Core Commands

| Command | Description | |---------|-------------| | ramp init | Initialize a new multi-repo project | | ramp install | Clone all configured repositories | | ramp up <feature> | Create feature branches across all repos | | ramp down <feature> | Remove feature branches and cleanup | | ramp rename <feature> <name> | Set a display name for a feature | | ramp prune | Batch remove all merged features | | ramp status | Show project status and active features | | ramp run <cmd> | Run custom commands (dev, test, etc.) |

See docs/commands/ for detailed command reference.

Configuration

Ramp uses .ramp/ramp.yaml:

name: my-project

repos:
  - path: repos
    git: git@github.com:org/frontend.git
  - path: repos
    git: git@github.com:org/api.git

setup: scripts/setup.sh      # Run after 'ramp up'
cleanup: scripts/cleanup.sh  # Run before 'ramp down'

default-branch-prefix: feature/

base_port: 3000
max_ports: 200
ports_per_feature: 2  # Allocate 2 ports per feature

commands:
  - name: dev
    command: scripts/dev.sh

Scripts receive environment variables for automation:

RAMP_PORT - Unique port for this feature
RAMP_TREES_DIR - Feature workspace path
RAMP_DISPLAY_NAME - Human-readable name (if set via --name)
RAMP_REPO_PATH_<NAME> - Path to each repository

See docs/configuration.md for full reference.

Example Setup Script

#!/bin/bash
# .ramp/scripts/setup.sh

# Install dependencies
cd "$RAMP_TREES_DIR/frontend"
npm install

cd "$RAMP_TREES_DIR/api"
npm install

# Start database on feature-specific port
docker run -d \
  --name "db-${RAMP_WORKTREE_NAME}" \
  -p "$RAMP_PORT_2:5432" \
  postgres:15

# Run migrations
cd "$RAMP_TREES_DIR/api"
npm run migrate

echo "✅ Ready! Run 'ramp run dev' to start"

Documentation

Getting Started - Your first Ramp project in 5 minutes
Configuration Reference - Complete ramp.yaml guide
Command Reference - Detailed command documentation
How-To Guides - Microservices, frontend/backend, custom scripts
Advanced Topics - Port management, git worktrees, troubleshooting

Use Cases

Microservices Development Coordinate features across multiple services with shared databases and networking

Frontend/Backend Projects Develop full-stack features requiring changes to both repos simultaneously

Library Development Work on libraries alongside applications that consume them with live linking

Multi-Environment Testing Set up isolated environments for testing features without affecting main development

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

# Development
go test ./...            # Run tests
go build -o ramp .       # Build binary
./install.sh             # Install locally

License

MIT License - see LICENSE for details.

Support

---

Get started now: brew install freedomforeversolar/tools/ramp or try the demo in demo/demo-microservices-app/