Multi-Repo Organisation Workspace Setup

Larger organisations maintain multiple repositories — a business operating system, client workspaces, product codebases, internal tooling. Each repository is its own Claude Code workspace with its own CLAUDE.md, but they can share a common base configuration distributed via a versioned template. The challenge is keeping shared standards consistent while allowing each workspace to have its own context.

Workspace identity — mandatory for multi-repo

Every workspace must know its own name, type, and GitHub remote. Without this, Claude cannot prevent commits going to the wrong repository or client rules bleeding into an unrelated workspace.

Store workspace identity in .claude/state/state.json:

{
  "workspace": {
    "name": "Acme Construction Ltd",
    "id": "acme-biz-os",
    "type": "client",
    "githubRepo": "acme-org/acme-biz-os"
  }
}

Validate before every git push: read workspace.githubRepo and compare against git remote get-url origin. If they don't match, abort. This is the single most important safety measure in a multi-repo environment.

Central template repository

Shared infrastructure — rules, hooks, and base skills that apply across all workspaces — should live in a central template repository rather than being manually maintained in each workspace. The workflow:

1. Template repo contains the base .claude/rules/, .claude/hooks/, and base skills
2. Each workspace is initialised from the template (or has an update mechanism to pull the latest base)
3. Workspace-specific additions go in the workspace itself; they are not pushed back to the template
4. When a rule changes in the template, push it to all workspaces — never maintain rules manually in each workspace separately; they drift within weeks

Managed policy for organisations

On Teams and Enterprise plans, administrators can set a managed CLAUDE.md at the system level that applies to every Claude Code session on enrolled machines. This is the correct mechanism for organisation-wide standards — it cannot be excluded or overridden by workspace-level config, ensuring compliance with data handling policies, approved tools, and behaviour standards.

Cross-workspace safety rules

Build these checks into your workspace rules to prevent accidents in a multi-repo environment:

• Git push validation — compare state.json repo against git remote get-url origin before every push
• Session banner — display workspace name at the start of every session (/day command) so the active workspace is always visible
• Cross-workspace warning — if a conversation references a client or project that doesn't match the current workspace, Claude flags it before proceeding
• MCP server scoping — register only the MCP servers relevant to each workspace; don't give a client workspace access to another client's tools