[FEATURE] Isolated multi-repo environments for Claude Code

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When working on a feature that spans multiple repositories, Claude Code can only see the directory it's launched in. This creates friction:

• You open multiple terminals and copy-paste context between them
• You manually symlink directories into a temp folder every time
• You spend the first 10 minutes of every conversation re-explaining the architecture
• Every developer on the team repeats this setup independently

This is especially painful in monorepo-adjacent setups where services, shared libraries, and frontends live in different repos but are tightly coupled.

Proposed Solution

A declarative config file (.claude/env.json) that describes everything Claude needs for a given feature:

{
  "feature": "auth-refactor",

  "links": [
    { "from": "./src",                        "as": "backend"  },
    { "from": "../frontend/src",              "as": "frontend" },
    { "from": "$MONOREPO/libs/shared",        "as": "shared"   },
    { "repo": "https://github.com/org/auth",
      "ref": "a3f9c12",                       "as": "auth-lib" }
  ],

  "deps": {
    "agents": [
      { "repo": "https://github.com/team/agents",
        "path": ".claude/agents/reviewer.md", "ref": "b1e4d87" }
    ],
    "skills": [
      { "path": "$SHARED/skills/security.md", "ref": "c2f1a09" }
    ]
  },

  "mcp": ["tracker", "playwright"],

  "agentRouting": {
    "explorer": "claude-haiku-4-5-20251001",
    "default": "claude-sonnet-4-6"
  }
}

A single command deploys a temporary directory with symlinks, versioned agents/skills, MCP config, and collected CLAUDE.md files from linked directories. The config is committed to the repo, so the entire team shares the same setup.

The analogy: docker-compose for Claude Code

Docker solved "works on my machine" for runtime environments. docker-compose went further — it let you declaratively describe a multi-service setup (databases, queues, backends) and spin it up with one command. Before that, every developer had their own setup scripts, their own local configs, their own onboarding pain.

Claude Code is in a similar place today. Each developer manually configures their AI working context — which directories Claude can see, which agents are loaded, which MCP servers are running. There's no way to share this setup, version it, or reproduce it across the team.

env.json is a docker-compose.yml for Claude Code. One declarative file describes the full working context. Commit it, and the entire team gets an identical Claude workspace.

A first step toward a harness

Right now Claude Code is a powerful but isolated tool — it works within a single directory, with whatever agents and skills happen to be there. There's no layer that orchestrates the broader environment Claude operates in.

This feature is a first step toward a harness — a structured way to manage what Claude sees, what tools it has, and how it's configured, per-feature and per-team. Today it's symlinks, agents, and MCP servers. Tomorrow it could be:

• Environment presets — env.json per branch, auto-activated on checkout
• Shared agent registries — team-wide agents versioned and distributed like packages
• Context budgets — declare which directories are high-priority vs. reference-only
• Session continuity — persist scratchpad state between down and up
• Hooks — run scripts before/after environment setup (install deps, start services, seed data)

The point is: as Claude Code becomes more capable, teams will need infrastructure to manage that capability. A declarative environment config is the natural foundation.

What it enables

• Reproducible environments — commit env.json, everyone gets the same Claude workspace
• Multi-repo projects — symlink local dirs and git repos into one workspace Claude can see
• Versioned agents and skills — pin to git refs, no surprises mid-sprint
• MCP servers — declare which servers Claude needs, pulled from global config
• Team-friendly paths — $ENV_VARS in paths so the same config works on every machine
• CLAUDE.md collection — automatically gathers context from linked directories

Proof of concept

I built a working CLI tool that implements this: https://github.com/project-Logic/claude-env

It handles init (interactive setup), up (deploy), down (cleanup), and status (list active environments). Built with Node.js, uses simple-git for repo operations.

Happy to adapt this into a PR if there's interest, or just leave it as a reference for a native implementation.

Workflow

# one person creates the config
claude-env init
git add .claude/env.json && git push

# everyone else
git pull
claude-env up
cd /tmp/claude-env-auth-refactor
claude

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Use case: payment system migration across 4 repos

A fintech team is migrating from Stripe to an in-house payment processor. The work touches:

• backend — payment API, webhook handlers, retry logic
• frontend — checkout flow, payment status UI, error pages
• shared-lib — payment types, validation schemas, currency utils
• infra — Terraform configs for new payment service, queue definitions

Four repos, tightly coupled. The team lead creates one config:

{
  "feature": "payment-migration",
  "links": [
    { "from": "$WORK/backend",           "as": "backend"    },
    { "from": "$WORK/frontend",          "as": "frontend"   },
    { "from": "$WORK/shared-lib",        "as": "shared"     },
    { "from": "$WORK/infra",             "as": "infra"      }
  ],
  "deps": {
    "agents": [
      { "repo": "https://github.com/org/claude-agents",
        "path": ".claude/agents/reviewer.md",  "ref": "v2.1" },
      { "repo": "https://github.com/org/claude-agents",
        "path": ".claude/agents/security.md",  "ref": "v2.1" }
    ]
  },
  "mcp": ["linear", "datadog"],
  "agentRouting": { "default": "claude-sonnet-4-6" }
}

Commits it to the backend repo. Now:

Day 1. Backend dev runs claude-env up. Claude immediately sees the full picture — API handlers in backend/, the types they share with frontend/, the Terraform definitions in infra/. It can trace a payment flow end-to-end and suggest changes across all four repos in one conversation.

Day 3. Frontend dev picks up the ticket. Same claude-env up, same environment. Claude already knows the new payment types from shared/, sees the API changes in backend/, and can update the checkout flow in frontend/ with full context. No onboarding, no "let me explain the architecture."

Day 5. Security review. The pinned security.md agent runs against all four repos at once — it catches that the new webhook handler in backend/ doesn't validate signatures, and that infra/ is missing encryption at rest for the payment queue. One environment, one review, all repos covered.

Day 7. New hire joins the team. They clone the repo, run claude-env up, and have the exact same setup as everyone else. Claude has the right context, the right agents, the right MCP servers. They're productive on day one.

Without claude-env, each of these moments costs 15–30 minutes of setup and context-building. Across a team of 6, over a 3-week migration, that's hours of wasted time — and countless moments where Claude gives worse answers because it can't see the full picture.

What it enables

• Reproducible environments — commit env.json, everyone gets the same Claude workspace
• Multi-repo projects — symlink local dirs and git repos into one workspace Claude can see
• Versioned agents and skills — pin to git refs, no surprises mid-sprint
• MCP servers — declare which servers Claude needs, pulled from global config
• Team-friendly paths — $ENV_VARS in paths so the same config works on every machine
• CLAUDE.md collection — automatically gathers context from linked directories

Proof of concept

I built a working CLI tool that implements this: https://github.com/project-Logic/claude-env

It handles init (interactive setup), up (deploy), down (cleanup), and status (list active environments). Built with Node.js, uses simple-git for repo operations.

Happy to adapt this into a PR if there's interest, or just leave it as a reference for a native implementation.

Additional Context

https://github.com/project-Logic/claude-env