Repo scripts

Repo scripts are shell scripts you configure per repository (Settings → Repositories → the terminal icon on a repo’s row) that Control Center’s server runs against a space’s worktree of that repo — the isolated checkout under <dataDir>/<workspaceId>/spaces/<spaceId>/repos/<repo>/ where agents work.

There are two kinds:

Script	When it runs	Use it for
Setup	Right after a worktree is provisioned for a space	Installing dependencies, generating files, copying .env
Archive	Just before a worktree is destroyed or garbage-collected	Cleaning up resources outside the worktree (docker networks, tunnels, external state)

Where scripts run

Both scripts run via bash -lc (a login shell, so Homebrew/nvm-installed tools are on PATH) with the worktree as the working directory, and these environment variables set:

Variable	Value
CC_WORKSPACE_PATH	The worktree (the script’s cwd)
CC_ROOT_PATH	The registered source repo — your own checkout
CC_SPACE_ID	The space the worktree belongs to
CC_SPACE_NAME	The space’s display name
CC_REPO_NAME	The repo’s display name

For example, a setup script that installs dependencies and brings in the repo’s gitignored .env:

pnpm install
cp "$CC_ROOT_PATH/.env" .env
pnpm run build

Failure behavior

• A setup script that exits non-zero (or exceeds its 5-minute timeout) fails the space’s provisioning: the space shows the failed state with a retry, and the run’s output tail is recorded. A retry provisions from a clean worktree and runs the script again — write setup scripts so a re-run after a partial install works (package managers already behave this way).
• An archive script is best-effort: a failure (or its 2-minute timeout) is recorded but never blocks deletion. Archive runs on GC paths with no one to answer a prompt (space deleted, PR merged, scheduled cleanup).

Setup runs only on a fresh worktree: re-dispatching agents into a warm space reuses the existing checkout and does not re-pay the install.

Run history

Every execution is recorded with its status, duration, exit code and a bounded output tail, visible in the same settings dialog under “Recent runs” (the repos.watchScriptRuns subscription streams it live).

Permissions

Scripts are shell the server executes, so writing them is restricted to workspace admins and guarded by the processSpawn action class — the same guardrail net that gates every other process-spawning operation.