wsm - Workspace Session Manager

Manage multi-session development workspaces with git worktrees.

Features

• Git Worktrees: Isolated development sessions with independent branches
• Port Allocation: Automatic port assignment per session to avoid conflicts
• Template System: Jinja2 templates for session-specific configuration
• Shared Libraries: Read-only libraries shared across sessions via symlinks
• Data Management: Copy or symlink data directories per session
• Shared Files: Common files (CLAUDE.md, project plans) symlinked into sessions

Installation

One-liner (recommended)

# Install wsm only
bash <(curl -fsSL https://git.mirus-tech.com/jmz/wsm/raw/branch/main/install.sh)

# Install and initialize workspace from config URL
bash <(curl -fsSL https://git.mirus-tech.com/jmz/wsm/raw/branch/main/install.sh) \
  -c https://example.com/workspace.yaml

# Install and initialize from local config
bash <(curl -fsSL https://git.mirus-tech.com/jmz/wsm/raw/branch/main/install.sh) \
  -c ~/workspace.yaml -d ~/my-workspace

The install script will:

1. Install uv if not present
2. Install wsm via uv tool
3. Optionally initialize a workspace from config

Manual installation

# Via uv (recommended)
uv tool install git+ssh://forgejo/jmz/wsm.git

# Or clone and install
git clone ssh://forgejo/jmz/wsm.git
cd wsm && uv tool install -e .

Quick Start

# Initialize workspace from configuration
wsm init -c workspace.yaml

# Add a session
wsm session add dev

# Add session with specific branch
wsm session add feature-auth -b feature/oauth

# List sessions
wsm session list

# Show session details
wsm session info dev

# Remove a session
wsm session remove dev

Configuration

Create a workspace.yaml file:

version: "1.0"
workspace_root: ~/workspace

repos:
  main-project:
    url: git@github.com:org/main-project.git
    placement: root
    default_branch: main

  my-library:
    url: git@github.com:org/my-library.git
    placement: libs
    default_branch: main

  shared-sdk:
    url: git@github.com:org/shared-sdk.git
    placement: libs
    readonly: true  # Shared across sessions

shared:
  claude_md:
    source: ./CLAUDE.md
    dest: CLAUDE.md

data:
  database:
    source: ~/data/db
    mode: copy
    dest: data/db

ports:
  base:
    web: 3000
    api: 8000
    db: 5432

templates:
  - source: session.env.j2
    dest: .env

Commands

Workspace Management

wsm init -c workspace.yaml     # Initialize workspace
wsm validate                   # Validate workspace structure

Session Management

wsm session add <name>         # Create new session
wsm session remove <name>      # Remove session
wsm session list               # List all sessions
wsm session info <name>        # Show session details

Sync Operations

wsm sync templates             # Re-render templates
wsm sync shared                # Re-sync shared files
wsm sync data                  # Re-sync data directories

Git Operations

wsm git status                 # Status across all sessions
wsm git fetch                  # Fetch all remotes
wsm git pull                   # Pull changes in sessions

Utilities

wsm ports                      # Show port allocation

Directory Structure

After initialization:

~/workspace/
├── workspace.yaml              # Configuration
├── CLAUDE.md                   # Shared file (source)
├── repos/                      # Bare repositories
│   ├── main-project.git/
│   └── my-library.git/
├── shared-libs/                # Read-only libraries
│   └── shared-sdk/
└── sessions/
    ├── dev/                    # Session 1
    │   ├── .env                # Generated from template
    │   ├── CLAUDE.md           # Symlink to shared
    │   ├── main-project/       # Worktree
    │   ├── libs/
    │   │   ├── my-library/     # Worktree
    │   │   └── shared-sdk/     # Symlink to shared-libs
    │   └── data/
    │       └── db/             # Copied data
    └── feature-auth/           # Session 2
        └── ...

Template Variables

Available in Jinja2 templates:

{{ workspace.root }}              # ~/workspace
{{ session.name }}                # "dev"
{{ session.number }}              # 1
{{ session.dir }}                 # ~/workspace/sessions/dev
{{ session.ports.web }}           # 3001
{{ session.ports.api }}           # 8001
{{ repos.main-project.branch }}   # Current branch
{{ data.database.path }}          # Full path to data

License

MIT