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. 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 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 for the full list of available flags and how global defaults work.

Required Inputs

Declare named inputs that every new workspace must supply before it can be created. Each input has a name (the env var key), a type (string / number / boolean) used for client-side validation, and an optional label / description for the workspace-create prompt. The supplied values become environment variables in the workspace session — visible to the agent, the terminal, and the setup/archive scripts.

See Required Inputs for the full reference.

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.

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