> ## 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.

# Project settings

> Share repository behavior and keep machine-specific Radius settings private.

Project settings define how Radius prepares a repository, creates worktrees, starts
commands, and configures the environment used by terminals and agents.

Use the settings page for local choices and `.radius/settings.toml` for behavior
that everyone working in the repository should share.

<CardGroup cols={2}>
  <Card title="Environment and files" icon="key" href="/docs/project-settings/environment-and-files">
    Configure variables, secrets, and ignored files copied into worktrees.
  </Card>

  <Card title="Git and worktrees" icon="git-branch" href="/docs/project-settings/git-and-worktrees">
    Choose the starting ref, remote, push behavior, and archive behavior.
  </Card>

  <Card title="Scripts and automation" icon="terminal" href="/docs/project-settings/scripts-and-automation">
    Configure startup, setup, run, and archive commands.
  </Card>

  <Card title="Settings file reference" icon="file-code" href="/docs/project-settings/file-reference">
    See every TOML field, default, and override rule.
  </Card>
</CardGroup>

## Open project settings

<Steps>
  <Step title="Open the project menu">
    Open the menu for a project or worktree group in the Radius sidebar.
  </Step>

  <Step title="Choose Settings">
    Radius opens a project-scoped settings tab with **Environment**, **Git**, and
    **Scripts** sections.
  </Step>

  <Step title="Choose what to share">
    Changes made in the settings page are local to your machine. Use **Open
    settings.toml** to edit shared repository settings in your preferred editor.
  </Step>
</Steps>

## Shared and local settings

<Tabs>
  <Tab title="Shared">
    `.radius/settings.toml` belongs in version control. Use it for team-wide
    variables, copied-file patterns, Git behavior, and scripts.

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    "$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
    version = 1

    [git]
    base_ref = "origin/main"

    [scripts]
    setup = "pnpm install"
    ```
  </Tab>

  <Tab title="Local">
    `.radius/settings.local.toml` contains machine-specific overrides and secrets.
    Radius writes it with user-only permissions and adds it to the repository's
    Git exclude file.

    ```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
    "$schema" = "https://radiusbrowser.com/schemas/settings.repo.schema.json"
    version = 1

    [environment.secrets]
    API_TOKEN = "local-secret"
    ```
  </Tab>
</Tabs>

Settings resolve in this order:

1. Radius defaults
2. `.radius/settings.toml`
3. `.radius/settings.local.toml`

Local values override shared values. Resetting local overrides returns the
project to its shared configuration.

<Note>
  Worktrees inherit effective settings from their source project. Radius does not
  copy `.radius/settings.local.toml` into a new worktree.
</Note>

## What project settings control

* Environment variables for terminals, lifecycle commands, and agent processes
* Gitignored files copied into new worktrees
* The Git ref and remote used for new worktrees and pushes
* Whether local worktree branches are removed after archiving
* Startup automation powered by the [Radius CLI](/docs/introduction)
* Worktree setup, named run commands, and pre-archive cleanup

Continue with the [settings file reference](/docs/project-settings/file-reference)
for the complete TOML format.