iws

Multi-repo workspace manager — git worktree orchestration for coordinated changes across multiple repositories.

Why iws?

When working on features that span multiple repositories (e.g., backend + frontend + shared libs), you need isolated branches and working directories for each. Manually managing git worktrees across repos is tedious and error-prone.

iws automates the entire lifecycle:

iws init → iws new → work on code → iws pr → iws done

Each workspace creates isolated git worktrees for selected repos, so your main branches stay clean.

Features

• Workspace lifecycle — create, manage, and clean up multi-repo worktrees with a single command
• Interactive TUI — browse workspaces, view status, and manage repos with keyboard navigation
• Smart PR creation — generate pull requests across all repos with automatic cross-references
• Editor integration — open workspaces in Zed, VS Code, or Cursor
• Claude Code integration — launch Claude Code sessions scoped to workspace context
• Shared files — copy common config files (.env, keyfiles) to each worktree
• SPEC.md templates — auto-generated workspace specification for tracking requirements

Installation

From source

git clone https://github.com/ne2030/iws
cd iws
cargo build --release

The binary is at ./target/release/iws. Move it to your $PATH:

cp target/release/iws ~/.local/bin/

Requirements

• Rust 1.70+ (for building)
• Git 2.20+ (worktree support)
• gh CLI (optional, for iws pr)

Quick Start

# 1. Navigate to your multi-repo project root
cd ~/projects/my-platform
#    my-platform/
#    ├── backend/      (git repo)
#    ├── frontend/     (git repo)
#    └── shared-lib/   (git repo)

# 2. Initialize iws (auto-detects git repos)
iws init

# 3. Create a workspace
iws new auth-refactor --repos backend,frontend

# 4. Work on your code in .workspaces/auth-refactor/{repo}/
#    Edit .workspaces/auth-refactor/SPEC.md to track requirements

# 5. Create PRs across all repos
iws pr auth-refactor

# 6. Clean up when done
iws done auth-refactor

Usage

Interactive TUI

iws

Launch the terminal UI for browsing and managing workspaces with keyboard navigation.

CLI Commands

How It Works

Project Structure

After iws init, a .workspaces/ directory is created:

my-platform/
├── backend/
├── frontend/
└── .workspaces/
    ├── config.toml              # Project config (repos, shared files)
    └── auth-refactor/           # Workspace
        ├── .workspace.toml      # Workspace config
        ├── SPEC.md              # Requirements & progress
        ├── .claude/CLAUDE.md    # Claude Code context
        ├── backend/             # Git worktree → backend repo
        └── frontend/            # Git worktree → frontend repo

Workspace Lifecycle

1. init — Scans current directory for git repos, creates .workspaces/config.toml
2. new — Creates worktrees with feature/{name} branches (or custom), copies shared files, generates SPEC.md
3. Work — Edit code in worktree directories. Main repo checkouts are untouched
4. pr — Pushes branches and creates GitHub PRs with cross-references between repos
5. done — Removes worktrees and local branches (warns about uncommitted changes)

Configuration

Project Config (.workspaces/config.toml)

[project]
name = "my-platform"
root = "/path/to/my-platform"

[repos.backend]
path = "backend"
default_branch = "main"
shared_files = [".env"]

[repos.frontend]
path = "frontend"
default_branch = "main"
shared_files = [".env.local"]

Workspace Config (.workspaces/{name}/.workspace.toml)

[workspace]
name = "auth-refactor"
created = "2024-03-20"

[repos.backend]
branch = "feature/auth-refactor"

[repos.frontend]
branch = "feature/auth-refactor"

License

MIT