Workspace - PairCoder Docs

PairCoder's workspace system enables multi-repo awareness, letting you manage related projects as a single workspace with shared configuration and coordinated operations.

Pro Feature

Workspace management requires a Pro or Enterprise license.

Overview

A workspace is a collection of related projects defined in a .paircoder-workspace.yaml file at your root directory. The workspace system provides:

Configuration - declare projects, paths, and dependencies in YAML
Discovery - validate project existence, git status, and PairCoder initialization
Coordinated operations - pull all projects, check status across repos
Audit logging - track cross-repo operations in .paircoder-audit.jsonl

Directory Structure

A workspace is a parent directory that contains your related projects as child directories. The workspace root holds the .paircoder-workspace.yaml config file, and each child project is its own git repository.

Directory Layout

my-suite/                          <-- workspace root (not a git repo)
├── .paircoder-workspace.yaml      <-- workspace config
├── .paircoder-audit.jsonl         <-- audit log (auto-created)
├── cli/                           <-- project: git repo with .paircoder/
│   ├── .git/
│   └── .paircoder/
├── api/                           <-- project: git repo with .paircoder/
│   ├── .git/
│   └── .paircoder/
└── website/                       <-- project: git repo with .paircoder/
├── .git/
└── .paircoder/

Key points:

The workspace root does not need to be a git repo - it is just a directory that groups your projects together
Each project must be a git repo (have a .git/ directory)
Projects can be nested (e.g., ./tools/cli) - they don't have to be immediate children
One workspace config per root directory - you cannot have multiple workspaces in the same directory

Where to Run Commands

You can run workspace commands from any project directory inside the workspace. The system resolves the workspace in two steps:

From your current directory, it walks up to find .git/ (your project root)
From that project root, it walks up again to find .paircoder-workspace.yaml (the workspace root)

This means:

Opening a project in your IDE works - cd api/ && bpsai-pair workspace status finds the workspace config above
Opening the workspace root directly does not work - if my-suite/ has no .git/, you'll get a "Not in a git repository" error
Any subdirectory inside a project works - cd api/src/routes/ && bpsai-pair workspace status still resolves correctly

Tip

If you want to run workspace commands from the root directory itself, initialize it as a git repo (git init) or open one of the child projects instead.

Getting Started

Initialize a Workspace

bash

# Specify projects explicitly
bpsai-pair workspace init --name my-suite --projects cli:./cli,api:./api

# Auto-scan for .paircoder directories
bpsai-pair workspace init --name my-suite --scan

# Overwrite existing config
bpsai-pair workspace init --name my-suite --projects cli:./cli --force

This creates .paircoder-workspace.yaml in your project root.

Check Status

bash

bpsai-pair workspace status
bpsai-pair workspace status --json

Shows workspace name and config path, each project's directory status (exists, git repo, branch, clean/dirty), and dependency relationships between projects.

Pull All Projects

bash

# Pull all projects
bpsai-pair workspace pull

# Pull a specific project
bpsai-pair workspace pull api

# Pull with rebase
bpsai-pair workspace pull --rebase

# JSON output
bpsai-pair workspace pull --json

Dirty projects are skipped with a warning. Use --rebase for git pull --rebase.

Configuration File

The .paircoder-workspace.yaml file defines your workspace:

yaml

name: my-suite
projects:
  cli:
path: ./tools/cli
consumers:
 - api
  api:
path: ./services/api
consumes:
 - cli
  website:
path: ./website
branch: main

Project Fields

Field	Required	Description
`path`	Yes	Relative path from workspace root
`repo`	No	Git remote URL
`branch`	No	Default branch name
`consumers`	No	Projects that depend on this one
`consumes`	No	Projects this one depends on

Validation

The parser validates your config on every operation:

All project paths must exist on disk
Consumer/consumes references must point to declared projects
Circular dependencies are detected and reported
Path traversal attempts are blocked

Audit Log

Every workspace operation is logged to .paircoder-audit.jsonl in the workspace root. Each entry records:

timestamp - when the operation occurred (UTC)
action - what happened (e.g., config_changed, pull_completed)
projects - which projects were involved
details - action-specific metadata
user - who performed the operation (optional)

Project Discovery

The discovery system checks each declared project for:

Check	What It Means
`exists`	Directory is present on disk
`is_git_repo`	Has a `.git` directory
`has_paircoder`	Has a `.paircoder` directory
`current_branch`	Active git branch name
`is_dirty`	Has uncommitted changes
`last_commit`	Short hash of latest commit

A project is considered "valid" when it exists, is a git repo, and has PairCoder initialized.

Fleet Check

Fleet check validates that every project in your workspace is running the same version of bpsai-pair. This catches version drift before it causes compatibility issues across repos.

Usage

bash

# Check version compliance across all workspace repos
bpsai-pair fleet check

# Automatically upgrade stale venvs to the current version
bpsai-pair fleet check --upgrade

# Machine-readable output for scripting
bpsai-pair fleet check --json

The command reads a workspace-index.yaml file to discover which projects belong to the workspace. This file is generated automatically when you initialize a workspace and lists each project's path and expected version. Fleet check walks through every entry, compares the installed bpsai-pair version in each project's virtual environment against the current version, and reports any mismatches.

Flags

Flag	Description
`--upgrade`	Upgrade any project whose bpsai-pair version is behind. Runs a pip install in each stale venv.
`--json`	Output results as JSON instead of the default table format.

Example Output

Terminal

$ bpsai-pair fleet check
Fleet Check - 3 projects
  cli      v2.23.0  OK
  api      v2.22.1  STALE (current: v2.23.0)
  website  v2.23.0  OK

1 project needs upgrade. Run with --upgrade to fix.

workspace-index.yaml

Fleet check relies on a workspace-index.yaml file located alongside .paircoder-workspace.yaml in the workspace root. This file maps each project name to its path and the expected bpsai-pair version:

yaml

version: "2.23.0"
projects:
  cli:
    path: ./tools/cli
    version: "2.23.0"
  api:
    path: ./services/api
    version: "2.22.1"
  website:
    path: ./website
    version: "2.23.0"

When you run bpsai-pair fleet check --upgrade, the command updates each project's venv and rewrites the version entries in workspace-index.yaml to reflect the new state.

Best Practices

Keep workspace root as the parent - place .paircoder-workspace.yaml in the directory that contains all your project subdirectories
Declare dependencies - use consumers/consumes to document how projects relate
Pull before work - run bpsai-pair workspace pull at the start of a session
Check status regularly - bpsai-pair workspace status shows if any project is dirty or behind
Use JSON for scripting - all commands support --json for machine-readable output