Docs
Download

Project Settings

The 8 per-project settings tabs (context, variables, worktree setup, recipes, commands, notifications and forge routing) and how they override global defaults.

Reviewed

Project settings override global defaults on a per-project basis. To reach them, open the scope switcher dropdown in the sidebar header and select Project. The option only appears when a project is open. For the app-wide defaults these layer on top of, see Global Settings.

Tip
The dialog remembers your last-active tab in each scope independently. Switching between Global and Project returns you to whatever tab you were last viewing in that scope.

The override-vs-inherit pattern

Most project settings have a global default behind them. The override-vs-inherit pattern is how Daintree shows you whether the field you're looking at uses the global value or its own override.

When a project setting overrides the global default, a small blue dot appears next to the label and the input gets a thin blue rim. Hover the row and a Reset to global button appears. When the setting inherits, the description below the input goes italic and shows the inherited value. Clearing an overridden field reverts it to inherited.

Note
Clearing an overridden field reverts it to inherited, so you don't have to click Reset to global explicitly. The button mainly earns its keep when the global value itself is empty and you want the field to read as inherited rather than blank.

General (project)

Project identity (display name, emoji, color, custom SVG icon) plus the dev server command and load timeout, an auto-inject option for Next.js Turbopack, and the two sections below.

Agent integrations

How much of Daintree the Claude Code agents launched in this project's worktrees can reach through the MCP server. Four tiers, set per project and picked up by newly launched agents:

  • Off (default for new projects): no Daintree MCP access at all
  • Workbench, read-only: worktree status, terminal output, file search, project history
  • Action: Workbench plus create worktrees, inject context, stage changes
  • System: Action plus commit, push, delete, and send terminal commands

Selecting System raises an inline warning, because some of those operations are irreversible or visible to teammates. This is the per-project ceiling for agents in your worktrees; the Daintree Assistant tier is a separate ceiling for help sessions. See MCP Server for what each tier contains.

In-repository settings

Off by default. Turning it on writes the shareable part of this project's configuration into a .daintree/ directory in the project root (.daintree/project.json for identity and .daintree/settings.json for settings), so your team gets the same configuration from the repository. When Daintree has loaded a project's settings from that directory it says so above the toggle.

Not everything goes in. Values marked sensitive stay in a local-only file, and terminal environment values are redacted before they are written. For the full split of what is committed versus what stays on your machine, see The .daintree directory.

Context

What goes into the context Daintree builds from your project. Two sections:

  • Excluded Paths: gitignore-style patterns excluded from every context Daintree assembles
  • Copy Tree: context size limit, per-file size limit, character limit, and always-include / always-exclude patterns, with a live preview of what the current settings would actually collect

This is the only place Copy Tree is configured: there is no separate Copy Tree tab in either scope. See CopyTree for what it produces and how to use it.

Variables (project)

The Variables tab defines KEY=VALUE pairs that Daintree injects into every new terminal session spawned in this project. That gives each project an isolated environment without touching your shell configuration or .env files. Use it for project-specific API endpoints, feature flags, tool configuration, or any value your agents and terminals need at runtime.

Variables are scoped to the project, not individual worktrees. Every worktree in a project shares the same set. Values stay local on your machine and are never written to .daintree/ files or committed to your repository, so each team member configures them separately. See Projects for more on project scope.

The editor splits into two blocks:

  • Inherited (Global): a read-only block at the top showing variables from the global Environment tab. Sensitive values display as ********. Each row carries a blue Global pill when it's inherited unmodified, or an amber Overridden pill when the project has its own value for that key.
  • Project: the editable block below, where you add, edit, and delete the project's own variables. A row that overrides an inherited key is visually linked back to the Inherited block.

Variable names must start with a letter or underscore and contain only letters, digits, and underscores. An invalid name shows an inline error on save. Duplicate names are flagged. Empty key rows are silently ignored. Changes apply on save and only affect new terminals; existing terminals keep the environment they spawned with until they're respawned.

Note
A Move N values out of shared settings action means sensitive-looking keys (anything whose name contains KEY, SECRET, TOKEN, PASSWORD, CREDENTIAL, or PASSPHRASE) are still sitting in the shared settings file. Click it to move them into the local-only sensitive store. They're still plaintext, just no longer in the file that gets committed. This only arises when in-repository settings are on: with the feature off there is no shared file to leak into.

Worktree Setup

What happens when a new worktree is created in this project:

  • Run Commands: quick-access project tasks (build, test, deploy) available from the worktree card and QuickRun
  • Branch Prefix: none, your username, or a custom prefix
  • Worktree Path Pattern: overrides the global pattern for this project; leave it empty to inherit
  • Terminal Defaults: shell, shell arguments, working directory, and scrollback, each on the override-vs-inherit pattern. Applies to new terminals only.
  • Resources: the remote-compute surface, below

See Worktrees for the rest of worktree configuration.

Resource environments

A worktree does not have to run on your machine. The Resources section defines named environments (each with the shell command used to reach it, such as an ssh, docker exec, or kubectl exec invocation) and a Default worktree mode picking whether new worktrees in this project are created locally or in one of those environments.

Environments are per-project because the machine a project builds on is a property of that project, not of Daintree. See Remote Compute for provisioning and the execution model.

Note
Resource environments and resource profiles are unrelated despite the shared word. Environments are where a worktree runs, and you configure them. Profiles are how aggressively Daintree throttles its own polling and caching under memory pressure, and there is nothing to configure. See Background resource management.

Recipes

Create, edit, and delete terminal recipes scoped to this project, and pin one as the default worktree recipe so it runs automatically whenever a worktree is created here. See Recipes for the full guide.

Commands

Define project-specific /slash command overrides and aliases that layer on top of global commands. See Unified Input for details on the command system.

Notifications (project)

Override global notification settings on a per-project basis. Project overrides layer on top of global settings, so you can silence a noisy project or add extra alerts for a critical one.

See Notifications & Sound for the notification system reference.

Code Forge (project)

Two overrides, both defaulting to auto-detect:

  • Forge remote: which git remote backs forge integration (issues, PRs, and pulse data) for this project. Auto-detect prefers origin, then any other remote a provider recognizes. Useful in a repo with several remotes where origin isn't the one you want.
  • Forge provider: pin this project to a specific provider instead of matching on the remote's hostname. Useful for a self-hosted forge on a hostname no provider claims.

A remote or provider that was saved and has since disappeared stays selected and is marked (unavailable), rather than silently resolving to something else. Whatever you pin here appears as the Override badge on that remote in Code Forge › General › Active project routing.

Environment variables across scopes

There are three places in Daintree to set environment variables. They have different scopes and different editors, so it's worth knowing which one does what.

  • Global Environment tab (Terminal group): variables injected into every terminal Daintree spawns, in every project. A key/value editor with explicit Save and Discard. Covered under Environment.
  • Project Variables tab (Project scope): the same injection, narrowed to one project, and overriding a global of the same name. Adds a read-only Inherited (Global) block above the editable rows. Covered above under Variables (project).
  • CLI Agents › per-agent › Runtime settings › Env block: per-agent variables that go into the agent's launch environment. The Default scope holds the agent's global env vars; a custom preset gets Env overrides that inherit from the Default scope until you promote an inherited row into an override. Covered under Presets and scopes.

The env-var editor

The CLI Agents env block uses Daintree's full env-var editor: a bordered table with Key, Value, and Actions columns. The per-row mechanics worth knowing:

  • Per-row left stripe: red on an empty key after blur, amber on a duplicate key or a value that looks like a secret, green when the row overrides an inherited entry
  • Eye toggle: appears on a row where the key matches Daintree's sensitive-name list or the value looks secret-like. It masks the value by default; reveal is session-scoped and resets when you reopen the dialog.
  • Key suggestion popover: the chevron next to the key cell opens an agent-specific list of recommended keys (e.g. ANTHROPIC_API_KEY for Claude). Arrow keys plus Enter to insert.
  • "Looks like a secret" advisory: when a value looks like a secret, an inline amber note reads "Looks like a secret: prefer ${ENV_VAR}". It's advisory only; the value still commits. The point is to nudge you toward referencing your shell environment instead of pasting the literal value.
  • Inherited rows: when the editor has an inherited set (a custom preset inheriting from the Default scope), inherited entries render as muted rows below the editable ones. A + Override button promotes a row to editable; once it's editable, the action button becomes Revert to inherited value. Clearing the value of an override on blur silently reverts it.
  • Import .env: opens the dialog below

Import .env

The Import .env button next to the env-var editor opens a two-step modal for pasting .env file contents.

Step 1: Paste. The textarea takes raw .env content. Keys must match [A-Za-z_][A-Za-z0-9_]*. Quoted values, comments, and export prefixes are supported. As you paste, a summary line below the textarea reads "N variables detected · M conflicts · K new · D duplicate keys in paste (last value kept)". Parse errors render as an amber callout listing the offending lines. The primary button reads Import N variables when there are no conflicts, and Review N conflicts when there are.

Step 2: Conflict resolution. Shown only when at least one pasted key already exists in the editor. Two radio options: Keep existing ("Only add new keys, leave colliding values untouched") or Overwrite conflicts ("Replace colliding values with the pasted ones"). Below the radios, a scrollable diff list shows each conflicting key with the old value in strikethrough, an arrow, and the new value in accent color. The primary button reads Import, keep existing or Import, overwrite conflicts depending on your selection. Resolution is binary across the whole import; you can't pick per-key.

Terminal env filter

Separately from your configured variables, Daintree filters the inherited shell environment before it spawns any terminal process. This keeps credentials from your shell out of agent and terminal sessions.

The filter strips variables that match a built-in blocklist of common credential names (such as ANTHROPIC_API_KEY, DATABASE_URL, GITHUB_TOKEN, AWS_SECRET_ACCESS_KEY, and others), plus any variable whose name contains credential-related keywords like SECRET, PASSWORD, TOKEN, PRIVATE_KEY, or CREDENTIAL at word boundaries.

The filter is hardcoded and not user-configurable. Variables in the DAINTREE_* namespace are always stripped from inheritance and re-injected fresh by Daintree itself. Your project-configured environment variables bypass the filter entirely, since they're intentional configuration rather than inherited credentials. For the full mechanism, see Security & Privacy.

Note
Variable values are injected verbatim. Expansion syntax like $HOME or ${PATH} is not supported inside the editor. If your shell RC file (e.g. ~/.zshrc) unconditionally exports the same variable, the shell value wins over the injected one. Project environment variables are also not injected into worktree lifecycle scripts (setup and teardown commands in .daintree/config.json).

Clearing session history

Daintree journals closed agent sessions so they can be resumed later, and there are two ways to clear that journal. They differ in reach, and neither lives on a project settings tab:

  • Per worktree: Clear session history on a worktree card deletes only that worktree's recorded resumable sessions, so those sessions stop appearing when you resume an agent there. Open sessions are unaffected.
  • Everywhere: Privacy & Data › Data & Storage holds the retention window and a clear that spans every project.

There is deliberately no per-project middle option. Bookmarked sessions survive both: deleting the bookmark is the only way to remove one. Both clears ask for confirmation first, and the confirmation is enforced inside the action rather than only at the button, so a future caller can't route around it. See Session Management for how the journal is built.

Background resource management

Daintree watches its own memory, battery state, thermal pressure, disk space, and agent count, and throttles itself when any of them gets tight: adaptive resource profiles, two tiers of memory-pressure mitigation, disk-space warnings, sleep prevention while agents run, and a governor on the terminal host process. None of it has user controls, and none of it is configured from this page.

It surfaces in two places. Diagnostics › Why slow? reports the active profile and escalates its presentation when the Efficiency profile is in force, so "why is everything sluggish" has an answer you can read. And worktree cards poll less often under pressure, which is the visible symptom of the same system.

The full mechanism (the signals, the thresholds, the rate limits, and what each profile changes) is documented once, at Performance. See also Session Management for how the Efficiency profile decides between destroying and freezing a cached project view.