workspaces

Workspaces

A Claude Code plugin for managing multi-repo development environments.

Installation • Quick Start • Commands • Configuration

---

If you work at a company with multiple repositories (api, frontend, admin, mobile, etc.), you know the pain: cloning everything, remembering which ports each service uses, figuring out what depends on what, and onboarding new team members who have to piece it all together.

Workspaces fixes this by giving Claude Code awareness of your entire project structure—not just the single repo you're sitting in.

Installation

Via Marketplace (Recommended)

In Claude Code, register the marketplace:

/plugin marketplace add patricio0312rev/workspaces-marketplace

Then install the plugin:

/plugin install workspaces@workspaces-marketplace

Manual Install

git clone https://github.com/patricio0312rev/workspaces.git ~/.claude/plugins/workspaces

Then add to ~/.claude/settings.json:

{
  "plugins": ["~/.claude/plugins/workspaces"]
}

Verify

Restart Claude Code and run:

/workspaces:init

Quick Start

1. Create a workspace

/workspaces:init

Claude will walk you through adding your projects—names, repos, paths, ports, and how they relate to each other.

2. Clone everything

/workspaces:clone all

3. Set up projects

/workspaces:setup all

Runs the setup commands you defined (npm install, migrations, etc.)

4. Verify it works

/workspaces:doctor

Checks prerequisites, versions, and runs health checks.

5. See where things stand

/workspaces:status

Shows git branches, uncommitted changes, and which services are running across all projects.

Commands

Command	What it does
/workspaces:init	Create a new workspace configuration
/workspaces:status	Git status + service status across all projects
/workspaces:clone [project|all]	Clone repositories
/workspaces:setup [project|all]	Run setup scripts
/workspaces:start [project|all]	Start development servers
/workspaces:stop [project|all]	Stop services
/workspaces:affected <project>	Show what depends on a project
/workspaces:search <query>	Search code across all projects
/workspaces:doctor	Check prerequisites and health

Configuration

Workspace configs live in ~/.claude/workspaces/<name>/WORKSPACE.md:

# Workspace: Acme Corp

## Company

name: Acme Corp
description: E-commerce platform

## Projects

| name     | repo                             | path                 | stack         | port |
| -------- | -------------------------------- | -------------------- | ------------- | ---- |
| api      | [email protected]:acme/api.git      | ~/work/acme/api      | Node, Express | 3000 |
| admin    | [email protected]:acme/admin.git    | ~/work/acme/admin    | React         | 3001 |
| homepage | [email protected]:acme/homepage.git | ~/work/acme/homepage | Next.js       | 3002 |

## Relationships

- admin -> api (REST client, consumes /api/v1/\*)
- homepage -> api (product catalog)

## Commands

start-all: cd ~/work/acme && docker-compose up -d
stop-all: cd ~/work/acme && docker-compose down

## Prerequisites

- Node.js 20+
- Docker

## Setup Scripts

api: npm install && npm run db:migrate
admin: npm install
homepage: npm install

## Health Checks

api: curl -s http://localhost:3000/health | grep -q "ok"

How It Works

Auto-detection: When you're in a project directory, workspaces figures out which workspace it belongs to (by path or git remote) and loads that context automatically.

Cross-project awareness: Ask "what depends on the api?" and Claude knows. Ask to search for a function across all repos, and it can.

Onboarding: New team member? They run three commands and everything is cloned, configured, and verified.

Plugin Structure

workspaces/
├── .claude-plugin/
│   └── plugin.json
├── commands/           # Slash commands
├── skills/             # Skill definitions
├── hooks/              # Session hooks
└── lib/                # Shared utilities

Tips