> ## Documentation Index
> Fetch the complete documentation index at: https://radiusbrowser.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup scripts

> Install dependencies and set up your workspace when you create a new worktree with setup scripts.

## Why use setup scripts?

When working in parallel with worktrees, each new worktree may need dependencies
installed or other development environment preparation. A setup script runs
those steps for you, so you do not have to repeat them manually every time you
create a worktree.

## Configure a setup script in project settings

You can configure setup for a project in **Settings → Scripts** or in
`.radius/settings.toml`. Radius runs it every time it creates a new worktree for
that project. It does not run when you reopen an existing worktree.

<video controls muted playsInline src="https://mintcdn.com/inspector-12805d8f/XifxWshzhd_l_q9V/videos/setup-scripts-why.mp4?fit=max&auto=format&n=XifxWshzhd_l_q9V&q=85&s=8d43e76591b627d3b9d155958476d10e" data-path="videos/setup-scripts-why.mp4" />

## Variables available to setup scripts

Radius automatically provides every setup script with information about the new
worktree and its place in the browser:

| Variable                | Value                                                                          |
| ----------------------- | ------------------------------------------------------------------------------ |
| `RADIUS_WINDOW_ID`      | Window containing the new worktree.                                            |
| `RADIUS_GROUP_ID`       | New worktree group.                                                            |
| `RADIUS_TAB_ID`         | Tab that opened the worktree. The workspace example uses it as a split anchor. |
| `RADIUS_PROJECT_ROOT`   | Source project that owns the settings.                                         |
| `RADIUS_WORKSPACE_PATH` | Path to the new worktree.                                                      |
| `RADIUS_WORKSPACE_NAME` | Name of the new worktree.                                                      |
| `RADIUS_DEFAULT_BRANCH` | Effective `git.base_ref` for the project.                                      |

The script also receives variables configured in the project's `[environment]`
settings. See [Environment and files](/docs/project-settings/environment-and-files)
for configuration and inheritance details.

## Install dependencies

For many projects, setup can be a single install command:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
setup = "pnpm install --frozen-lockfile"
```

Radius runs the command as a background process from the new worktree directory,
so setup does not open or take over a terminal tab. Use the install command
appropriate for your project, such as `npm install`, `bundle install`, or
`uv sync`.

## Set up your workspace

For instance, here is a short example that installs dependencies, then opens a
terminal and localhost server beside the new worktree's chat:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
setup = """
pnpm install --frozen-lockfile

radius group rename "$RADIUS_GROUP_ID" "Development"
terminal="$(radius tab open "radius://terminal" --project-path "$RADIUS_WORKSPACE_PATH" --right-of "$RADIUS_TAB_ID" --size 50%)"
radius tab open "http://localhost:3000" --below "$terminal" --size 40%
"""
```

<Tip>
  In **Settings → Scripts**, paste only the commands inside the multiline string.
  Radius stores them as one setup command for you.
</Tip>

## Move a larger setup into a file

When the setup becomes long enough to test or reuse on its own, move it into a
shell script. Save this as `scripts/setup-worktree.sh`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
#!/usr/bin/env bash
set -euo pipefail

pnpm install --frozen-lockfile

radius group rename "$RADIUS_GROUP_ID" "Development"
terminal="$(radius tab open "radius://terminal" --project-path "$RADIUS_WORKSPACE_PATH" --right-of "$RADIUS_TAB_ID" --size 50%)"
radius tab open "http://localhost:3000" --below "$terminal" --size 40%
```

Then tell Bash to run the file:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[scripts]
setup = "bash scripts/setup-worktree.sh"
```

See [Run and archive scripts](/docs/project-settings/run-and-archive-scripts) for
named run commands and pre-archive cleanup.