---
title: Per-Repo Settings
description: Custom instructions, setup and archive scripts, and branch preferences for each repository.
---

Claudette lets you configure settings per-repository — instructions for the agent, scripts that run on workspace creation and archive, and branch naming preferences.

## Accessing Repo Settings

Open `Settings > Repository` (or press `⌘/Ctrl + ,` and select a repository from the sidebar).

## Setup Script

A shell command that runs automatically when a new workspace is created. Use this to install dependencies, set up the environment, or run migrations.

**Examples:**

```bash
# Node.js project
npm install

# Python project
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt

# Elixir project
mix deps.get && mix ecto.setup
```

The script runs in the workspace's worktree directory using your platform's default shell — `sh -c` on macOS and Linux, `cmd.exe /S /C` on Windows — so write the script in whichever syntax matches your host. [Workspace environment variables](/claudette/features/settings/#environment-variables) like `$CLAUDETTE_WORKSPACE_NAME` and `$CLAUDETTE_ROOT_PATH` are available in setup scripts (use `%CLAUDETTE_WORKSPACE_NAME%` etc. in `cmd.exe`).

By default, Claudette shows a confirmation modal with the script contents before running it. Tick **Skip confirmation when running setup scripts** in the repo settings (or **Always run setup scripts for this repo** in the modal) to opt into auto-run for that repository.

## Archive Script

A shell command that runs when a workspace is archived, **before** the worktree is removed. Use this to push final commits, tear down services, or stash uncommitted work.

**Examples:**

```bash
# Push any unpushed commits to the remote
git push --all && git push --tags

# Stash uncommitted changes so they aren't lost
git stash push -u -m "claudette archive"

# Tear down a docker-compose stack started by setup
docker compose down
```

The script runs in the workspace's worktree directory through the same platform shell as the setup script (`sh -c` on macOS/Linux, `cmd.exe /S /C` on Windows) and has access to the same workspace environment variables. The worktree is still on disk while the script runs, so any commands that need to read workspace files will work as expected.

By default, Claudette prompts before archiving when an archive script is configured — the modal shows the script contents and lets you choose **Run & Archive** or **Archive without running**. Tick **Skip confirmation when running archive scripts** in repo settings (or **Always run archive scripts for this repo** in the modal) to skip the prompt for that repository.

If the archive script fails or times out, Claudette continues with the archive — a system message in the workspace's last chat session records the script output and exit status, so you can inspect what happened.

## Environment Provider Overrides

The **Environment** section in each repo's settings shows every env-provider plugin (direnv, mise, dotenv, Nix devshell) with its live status, a per-repo enable toggle, and a **Settings** drawer with the plugin's manifest-declared settings as per-repo overrides (currently `timeout_seconds`). Setting a value here only applies to workspaces in this repo; clicking **Use global default** on an overridden field clears the per-repo value and falls back to **Settings → Plugins**.

The most common reason to set a per-repo override is **timeout**: the default cap is 120 seconds, which covers most cold direnv/mise/Nix runs. Some Nix flakes (large transitive closures, slow substituter networks) routinely exceed that. Bump `Timeout (seconds)` for those repos rather than globally; the global value still applies everywhere else.

### One-time per-repo trust prompt

direnv and mise both refuse to evaluate config files that haven't been explicitly approved per worktree (`direnv allow` / `mise trust`). The first time a workspace under a repo hits this, Claudette opens the **Environment trust needed** modal with one row per affected provider:

- **Trust** — runs the trust command (`mise trust` / `direnv allow`) in the repo's main checkout AND every existing worktree under it. For mise, Claudette persists `repo_trust = "allow"` so future workspaces in this repo can auto-trust on first resolve. For direnv, Claudette records approved `.envrc` SHA-256 digests instead: future worktrees auto-allow only when their `.envrc` content matches a digest you approved.
- **Disable for project** — toggles the per-repo `enabled = false` flag so the dispatcher skips the provider entirely for any worktree under this repo. Other env-providers still run. You can re-enable from the row's toggle in Repo Settings → Environment.
- **Decide later** — dismisses the modal without persisting a choice. The same prompt surfaces again the next time a workspace fails resolve.

If you dismissed the prompt (or want to revisit the decision later), the same modal is reachable from **Repo Settings → Environment**: trust-blocked providers render a **Resolve…** button on their row that re-opens the same prompt. Toggling a disabled provider back on also re-runs the prompt automatically if the underlying config is still untrusted. Non-trust errors (broken TOML, flake eval failure) still surface inline via a **Details** disclosure — the modal isn't the right surface for those, and re-running the trust command wouldn't help.

The decision is per-repo, not global, so trusting one project's `.envrc` doesn't affect any other. Direnv approvals are also content-aware: editing `.envrc` changes its digest and Claudette prompts again before using the changed environment. The pre-0.24 global `auto_allow` / `auto_trust` toggles have been removed; existing mise `auto_trust` opt-ins migrate to per-repo trust state, while direnv prompts again so each `.envrc` digest can be reviewed explicitly.

### Loading state

While an env-provider is resolving, Claudette surfaces the active plugin and elapsed time in three places: the workspace's row in the sidebar (spinner + tooltip), the chat composer placeholder, and an overlay above the integrated terminal. The terminal won't open a prompt and the agent won't spawn until the env layer is ready or fails. You can still prepare the next chat turn while this runs: pick a model, toggle Plan mode, adjust Thinking/effort, attach files, or open the composer overflow menu; only sending stays blocked until the environment is ready.

If the preparation IPC stalls, Claudette times out the wait, marks the workspace environment as failed, and re-enables the composer/terminal instead of leaving the workspace stranded. The chat banner includes **Retry environment setup**, which evicts the env-provider cache for that workspace and runs preparation again without requiring an app relaunch.

### Live provisioning output in the Claudette Terminal

For long-running provisioning (`nix print-dev-env` on a cold flake can be 30-90s; a fresh `mise install` can stretch much further), Claudette streams the env-provider plugins' **stderr** (the human-readable progress chatter) and **all** of the setup-script's stdout/stderr into the workspace's **Claudette Terminal** tab. Env-provider **stdout** is intentionally suppressed from the terminal — providers like `direnv export json` / `mise env --json` / `nix print-dev-env --json` emit the full machine-readable environment payload there, which routinely contains secrets (`AWS_SECRET_ACCESS_KEY`, `GH_TOKEN`, …) that don't belong in a transcript on disk. When env-provider resolve starts on a fresh workspace, the bottom terminal panel auto-opens so the output is visible without hunting for the toggle — your current tab focus is preserved if you already have another terminal open.

If you explicitly close the terminal panel (via the toggle or `Ctrl/Cmd+\``), that closure sticks: env-preparation no longer auto-opens it on subsequent workspace switches until you re-open the panel yourself. The override is global, not per-workspace, so a single dismissal silences auto-open across the whole app session. Open the panel again to opt back into auto-open behavior.

Because the output lands in a real terminal (xterm.js), native ANSI colors from `nix -L`, `direnv`, and `mise` render directly — no parallel renderer, no stripped escape codes. A dim cyan `── plugin ──` header separates plugin transitions so the direnv → nix-devshell handoff in a wall of build chatter is easy to scan. The `.claudette.json` setup script's stdout / stderr writes into the same tab under a `setup-script` header, so a slow `bun install` is visible in real time instead of waiting for the SetupScriptBanner to appear in the chat transcript.

The Claudette Terminal can be disabled in **Settings > General > Claudette Terminal** if you'd rather opt out. With it off, env-provider and setup-script output still streams to a workspace-scoped file at `$TMPDIR/claudette-workspace-terminal/<workspace-id>/terminal.output` (useful for debugging from outside Claudette), and provisioning continues normally — only the read-only mirror tab is suppressed.

**Capped scrollback.** `terminal.output` is a tail-bounded ring, not an append-only log. When the file would exceed **64 MiB**, the next write rewrites it in place to keep the most recent **32 MiB** preceded by a `[claudette: terminal output truncated, keeping last 32 MiB]` banner. Older history is dropped. This stops a long-running background process (e.g. a chatty dev server) from filling the file unbounded — see [issue #937](https://github.com/utensils/claudette/issues/937) for the original incident. The xterm.js tail reader handles the in-place shrinkage transparently. If you need the full history of a long session, redirect the underlying command to a log file you own — `terminal.output` is a live tail, not an archive.

**Verbose flags applied automatically.** The bundled `env-nix-devshell` plugin passes `-L` (`--print-build-logs`) to `nix print-dev-env` so per-derivation build output streams to the terminal instead of buffering inside Nix. `env-mise` and `env-direnv` rely on the providers' default stderr chatter — both are already informative.

**Secrets warning.** The env-provider stdout suppression above is a defense-in-depth measure, not a complete redaction guarantee — `direnv` scripts (and noisy setup scripts) can still echo secret values through **stderr**, which the terminal does surface. Treat the terminal's contents the same way you'd treat any terminal session inside the workspace; don't share screenshots without redacting.

## Claude CLI Flag Overrides

The **Claude CLI flags** section in repo settings lets you override the global flag defaults for workspaces in this repository. Each flag has three states:

| State | Behavior |
|-------|----------|
| **Inherit** | Falls back to the global value from **Settings > Claude CLI flags** |
| **Force on** | Flag is enabled for every workspace in this repo |
| **Force off** | Flag is disabled for every workspace in this repo |

Only flags explicitly set to **Force on** or **Force off** are active as overrides — flags left at **Inherit** are not stored and have no effect. This means a per-repo entry can never silently win over a global setting unless you intentionally set it.

The **Inherited** section (read-only) shows which flags are currently coming from global defaults, along with their values, so you can see the full effective configuration without switching screens. Promote an inherited flag to a repo override by clicking the **Override** button on its row.

See [Agent Configuration → Claude CLI Flags](/claudette/features/agent-configuration/#claude-cli-flags) for the full list of available flags and how global defaults work.

## Custom Instructions

Text that is appended to the agent's system prompt at the start of every chat in this repository. Use this to give the agent context about your project:

```
This is a Django REST API using Python 3.12. Use pytest for tests.
Follow the existing code style — type hints on all function signatures.
```

## Branch Rename Preferences

Custom instructions sent with the agent's first message to guide how it names the workspace branch. This only applies if the branch hasn't already been renamed.

## CI Auto-Fix Overrides

Each repository can inherit, enable, or disable the global **Auto-fix CI failures** setting. A repository can also provide its own prompt template, which overrides the global CI auto-fix prompt for workspaces in that repo.

Leave the repo prompt override empty to use the global template. The same variables are available as in the global setting: `{{failed_checks}}`, `{{failure_logs}}`, `{{branch}}`, `{{pr_title}}`, `{{pr_url}}`, `{{pr_number}}`, and `{{all_checks}}`.

## `.claudette.json`

You can also configure these settings via a `.claudette.json` file in your repository root. This is useful for sharing settings with your team via version control.

```json
{
  "scripts": {
    "setup": "bun install",
    "archive": "git push --all && git push --tags"
  },
  "instructions": "This is a Next.js 15 app using the App Router. Use TypeScript strict mode."
}
```

### Schema

| Field | Type | Description |
|-------|------|-------------|
| `scripts.setup` | string | Shell command to run on workspace creation |
| `scripts.archive` | string | Shell command to run before a workspace is archived |
| `instructions` | string | Custom instructions for the agent |

:::note
`.claudette.json` settings take precedence over settings configured in the UI. If both are present, the file wins.
:::

Unknown keys in `.claudette.json` are silently ignored, so the file is forward-compatible with future settings.

## See also

- [Checkpoints & Forking](/claudette/features/checkpoints-and-forking/) — repo-scoped chat history and snapshot retention
- [MCP Servers](/claudette/features/mcp-servers/) — repo-scoped MCP configuration
- [SCM Providers](/claudette/features/scm-providers/#environment-provider-plugins) — env-providers that augment scripts and agents per repo
