Codespaces Tooling

"Virtual Monorepo" orchestration for multi-repo ecosystems

Dev infrastructure for managing multiple separate Git repositories as a cohesive workspace — treating code like an ecosystem rather than a monolith.

Philosophy: Why Multi-Repo?

This tooling embodies the architectural and social superpower of multi-repo: focused, modular, open-by-default development.

1. The "Focused Contribution" Effect

In a monorepo, a new contributor must download gigabytes and understand a massive build system to fix a typo in one library.

Multi-repo win: Clone just the repo you need. Run tests for just that utility. Barrier to entry is near zero. It feels "hackable."

2. "Open Source by Default" Mentality

Monorepos act like black holes — code goes in and never comes out. Extracting a piece for open source is a nightmare of tangled dependencies.

Multi-repo win: Build a nice component in its own repo, flip visibility to "Public" later. No refactoring drama.

3. Enforced Modular Discipline (API First)

In monorepos, developers import internal helpers across folders, creating spaghetti dependencies.

Multi-repo win: Physical separation forces clear interfaces. You think about versions (v1.0.1). This friction prevents inseparable knots.

4. Hybrid Privacy ("Secret Sauce" Strategy)

The Setup:

• Repo A (Public): SDK or API client for customers
• Repo B (Public): Documentation site or UI kit
• Repo C (Private): Proprietary algorithm that makes you money

Small team works on secret stuff while community improves public tools. Doing this in a single Git repo is a permission nightmare.

Contents

Workspace Management

• clone.ts — Auto-clone missing repos with dependency awareness
• sync.ts — Dependency-aware sync across repos
• branch.ts — Multi-repo branch operations
• git.ts — Git operation wrappers

Development Tools

• link.ts — Local package linker for workspace development
• typecheck.ts — Affected type checking across repos
• dev.ts — Multi-repo dev runner

Infrastructure

• state.ts — State management
• workflow.ts — Git workflow automation
• hook.ts — Git hooks
• daemon.ts — Background daemon
• format.ts — Table formatting for CLI output

Usage

Workspace Setup

# Show full workspace status (git, changes, branches)
codespaces status

# Compact view (one line per repo)
codespaces status --compact

# Focus on changed files
codespaces status --changes

# Focus on branch info
codespaces status --branches

# Clone missing repos from config
codespaces clone

# Sync all repos (parallel for speed)
codespaces sync --parallel

Branch Operations

# Create branch across all repos
codespaces branch create feature-auth

# Checkout branch across all repos
codespaces branch checkout main

# Clone specific branch from remote
codespaces branch clone feature-auth

# List available remote branches
codespaces branch remotes

Development Tools

# Link local packages together for development
codespaces link

# Link packages for specific repo only
codespaces link ralph

# Show current link state
codespaces link status

# Clean up all symlinks
codespaces unlink

# Type check all repos
codespaces typecheck

# Type check only repos with changes
codespaces typecheck --changed

# Type check changed repos + their dependents
codespaces typecheck --affected

# Start all dev servers
codespaces dev

# Start specific repo + its dependencies
codespaces dev ralph

# Start filtered set (e.g., only public repos)
codespaces dev --filter type:public

Per-Repo Configuration

Each repo can have a .codespaces.json file in its root to override or extend auto-discovered settings.

See .codespaces.json.example for a full template with all options and common scenarios.

{
  "dev": {
    "command": "bun run watch",
    "port": 3000,
    "env": {
      "DATABASE_URL": "postgres://localhost:5432/dev"
    },
    "cwd": "packages/backend",
    "healthCheck": "http://localhost:3000/health"
  },
  "typecheck": {
    "command": "tsc --noEmit",
    "cwd": "packages/backend",
    "skip": false
  },
  "link": {
    "exclude": ["some-package"],
    "include": ["@workspace/another-package"]
  }
}

| Section | Field | Description | |---------|-------|-------------| | dev | command | Command to run (default: auto-discovered from package.json) | | | port | Port the service listens on | | | env | Environment variables to set | | | cwd | Working directory (relative to repo root) | | | healthCheck | URL to check before starting dependents | | typecheck | command | Type check command (default: "bun tsc --noEmit") | | | cwd | Working directory | | | skip | Skip type checking for this repo | | link | exclude | Packages to exclude from linking | | | include | Additional packages to link |

Structure

@codespaces/tooling/
├── src/
│   ├── cli.ts        # CLI entry point
│   ├── clone.ts      # Clone manager
│   ├── branch.ts     # Multi-repo branch operations
│   ├── sync.ts       # Dependency-aware sync
│   ├── git.ts        # Git operation wrappers
│   ├── link.ts       # Local package linker
│   ├── typecheck.ts  # Affected type checker
│   ├── dev.ts        # Multi-repo dev runner
│   ├── format.ts     # Table formatting
│   ├── state.ts      # State management
│   ├── workflow.ts   # Git workflow automation
│   ├── hook.ts       # Git hooks
│   └── daemon.ts     # Background daemon
├── config.json       # Repo configuration
└── state.json        # Persisted state