[FEATURE] Allow cloud environment setup scripts to be defined in the repository

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

Cloud environments solve the "toolchain isn't pre-installed" problem with
setup scripts, and the environment cache makes the cost one-time. That part
works well. The gap is where the script lives.

Setup scripts are configured per environment in the dialog at claude.ai/code,
and environments created there are personal to the account. Shared
environments exist only on Team and Enterprise, and only an Owner can create
them. So for a Pro/Max team of five working on the same repository, all five
people have to independently discover the same script and paste it into
their own environment. Nothing about that provisioning step is captured by
the repository, reviewable in a PR, or versioned alongside the code that
depends on it.

This is inconsistent with how everything else works. The docs say "To make
your own configuration available in cloud sessions, commit it to the repo,"
and CLAUDE.md, .claude/settings.json, .mcp.json, .claude/skills/, agents and
commands all follow that rule. Environment provisioning is the one thing
that cannot.

SessionStart hooks are not a substitute. Per the docs they run after Claude
Code launches, on every session including resumed ones, and they do not
benefit from environment caching. The documented split is explicit: setup
scripts provision the VM (toolchains that are not pre-installed), hooks
handle project setup like npm install. There is currently no repo-committed,
cached, pre-launch provisioning path.

Concrete example: #11627 asked for the .NET SDK in the base image and was
closed with "use a setup script." That answer is correct, and it is also why
this matters. 74 people upvoted a request whose resolution is a snippet that
every one of them now has to find and maintain separately. The same applies
to #55000 (Erlang/Elixir) and to any toolchain outside the pre-installed
list.

Proposed Solution

Let the repository define the setup script.

For example, a .claude/setup.sh file, or a "setup" key in a
.claude/environment.json, read when a cloud session starts and cached
exactly the way the dialog-configured script is cached today. The same
constraints would apply (must exit zero, must finish within roughly five
minutes, needs network access for installs).

Precedence is your call. Either of these would be reasonable:

• The repo-defined script runs in addition to the environment's script
• The repo-defined script overrides the environment's script when present

Ideally this applies to every surface that starts a cloud session, including
claude --cloud, Claude Tag and routines, so a repository carries its own
provisioning wherever it is opened.

Alternative Solutions

• Paste the same script into each member's environment manually. This is the

status quo. It does not scale, it drifts silently, and new members have no
signal that a working recipe already exists inside the team.

• Organization-shared environments. Team and Enterprise only, admin-managed,

and still not versioned alongside the code that depends on them. A
dependency change and its provisioning change cannot ship in one PR.

• SessionStart hooks. They run after Claude Code launches, are not cached,

and per the docs are intended for project setup rather than provisioning
toolchains. Using them for large installs adds latency to every session.

• Self-hosted environments. Viable for organizations that operate their own

runners, but far too heavy for a team that just needs one extra SDK.

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

A .NET 10 repository with a team of four on Pro/Max plans.

Today:

1. A developer opens claude.ai/code and starts a cloud session.
2. The build fails because the .NET SDK is not in the base image.
3. They search, eventually find a closed issue (#11627), and copy the

install script into their personal environment.

1. Each of the other three developers repeats steps 1 to 3 independently.

Anyone who does not gets a build failure with no indication that a
working recipe already exists inside the team.

1. When the project moves to a new SDK version, all four environments have

to be edited by hand, and nobody can tell which ones were missed.

With a repo-defined setup script:

1. One PR adds .claude/setup.sh. It is reviewed like any other change.
2. Every cloud session for every member starts with the SDK present, and so

do Claude Tag sessions and routines.

1. An SDK bump is a one-line diff with history, not four manual edits.

Additional Context

Related issues:

• #11627 - .NET SDK in the web runtime environment (74 upvotes, closed with

"add it with a setup script")

• #55000 - Erlang/Elixir toolchain, same shape of request
• #71629 - Trusted egress allowlist out of sync with tooling

Prior art: Cursor cloud agents read .cursor/environment.json from the
repository, with an install command and an optional Dockerfile reference.
Cursor describes the development environment itself as a product whose users
are agents, which is the same idea being asked for here.

This request is deliberately not about any single language. It is about
where provisioning lives. Adding one more toolchain to the base image helps
the users of that toolchain; making provisioning repo-defined helps every
project whose stack is outside the default list, and removes the need for
most future "please pre-install X" requests.