Per-Repo Settings

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:

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

# 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, then persists repo_trust = "allow" so any future workspace in this repo auto-trusts silently on first resolve via the env-provider plugin’s retry path.
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. The pre-0.24 global auto_allow / auto_trust toggles have been removed; users who had them enabled are migrated automatically to per-repo repo_trust = "allow" for every repository they had at the time of upgrade.

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.

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.

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

{
  "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

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