Skip to main content

The .daintree Directory

The .daintree/ directory in your repository: shared project identity and settings, team presets, recipes, project plugins, worktree lifecycle scripts, and the plugin state Daintree writes there at runtime.

Updated
Reviewed

The .daintree/ Directory

Daintree supports an optional .daintree/ directory at the root of your repository, in the same spirit as .vscode/ or .devcontainer/. When it is present, Daintree reads it on project open, so anyone who clones the repo picks up the same project identity, settings, recipes and lifecycle scripts without setting them up again.

Built-in project settings keep environment-variable values local, and recipe serialization redacts environment values. That is not a guarantee about everything under .daintree/: plugin storage, plugin settings, scripts and Assistant content can contain sensitive data. Review the files before committing them. For a lightweight (non-git) workspace, Daintree skips automatically writing repository identity files; you can still create project content deliberately.

Enabling In-Repository Settings

Open Project Settings > General (File > Project Settings…, the project switcher's Project settings… row, or the toolbar project pill's right-click menu) and scroll to In-repository settings. Clicking the Store settings in repository switch expands a confirmation panel listing the files Daintree will create. The switch itself stays off until you click Confirm and enable, which writes them.

From then on, Daintree writes .daintree/project.json and .daintree/settings.json and keeps them in sync as you change settings, and syncs existing project recipes into .daintree/recipes/. These are separate from the settings.json Daintree keeps in its own app data directory; the in-repo pair holds only the shareable subset.

The switch stays off until Confirm and enable writes the files
Note

Disabling in-repository settings is non-destructive. Daintree stops synchronizing shared project settings and recipes, but the existing files stay in the repo, and a teammate cloning it still gets the identity and settings applied on open.

What lives in .daintree/

The contents split into two groups, and the split matters mostly because of what turns up in git status.

Things you commit

PathContains
.daintree/project.jsonProject identity: a version (always 1), the project id, plus name, emoji and color. The id is the anchor that lets Daintree recognize the project after its folder moves: don't strip it. A file with no valid integer version is rejected outright.
.daintree/settings.jsonThe shareable subset of project settings: run commands, dev server command and load timeout, excluded paths, CopyTree settings, worktree path pattern, and the shareable terminal settings.
.daintree/recipes/Per-project recipes, one JSON file each, synced from local recipe storage while in-repo mode is on. Env var values are redacted; the keys are preserved.
.daintree/presets/<agentId>/*.jsonTeam-shared agent presets, read per agent id. Read-only as far as Daintree is concerned: you write these, it never does. This is the one entry most teams want and most don't know about.
.daintree/config.jsonWorktree lifecycle scripts and resource environments. Also read-only: nothing in Daintree ever writes it. Its commands only run once you have approved them.
.daintree/plugins/<plugin-folder>/Project plugins: a plugin.json manifest and built plugin entrypoints/assets. Commit the files needed to load the plugin so a teammate can review and trust the same project tools.
.daintree/assistant/Project-scoped custom commands, skills and instructions for the Daintree Assistant: .claude/commands/<name>.md, .claude/skills/<name>/SKILL.md, .codex/skills/<name>/SKILL.md, .agents/skills/<name>/SKILL.md, an instructions.md, and a reference/ folder of files the Assistant can read. They override the same names in ~/.daintree/assistant, reach only the Assistant (never ordinary agent terminals), and are used on the next Assistant launch without a separate approval step, so review them like code. Project-local MCP servers and hooks are not loaded. Those are loaded from the global folder only after you turn that on; project instructions and skills can still guide the Assistant's normal tools. There is no .daintree/commands/ directory.

Things Daintree writes at runtime

PathContains
.daintree/plugin-settings/<pluginId>.jsonProject-scoped plugin settings, keyed by manifest id (publisher.name). New secret settings don't land here: they are encrypted with the OS keychain and saved in the local settings, for this project, of the machine running the plugin. Older versions could leave secrets in this file; Daintree now ignores them but doesn't remove them, so inspect the file and its Git history before sharing.
.daintree/plugin-storage/<pluginId>.jsonPlaintext project-scoped plugin storage, keyed by manifest id. Worktree-scoped storage uses the same relative path inside that worktree. Runtime project-instance ids are not used as repository filenames.
.daintree/data/<pluginId>/<databaseId>.dbA SQLite database a project plugin declares with location: "project", unless the plugin names its own path inside the repository. A plugin's per-machine databases live in its data directory outside the repository instead.
.daintree/daintree-remoteA generated executable shell wrapper (mode 0755) that forwards arguments to a Remote Compute environment's connect command, so agents get a stable invocation path that survives endpoint changes. Written per worktree when a resource environment is active.

Whether the second group belongs in version control is a judgment call: plugin settings a team wants to share are worth committing, plugin storage and the generated remote wrapper usually are not. A project database is shared data by design, so commit it only if the team should see the same records, and check what the plugin stores in it first.

What's shared vs. machine-local

The shareable/local split is a field-level classification inside settings.json, not a separate file. Every project settings field carries a classification, and only fields marked shareable are ever written to the committed file. These are never written:

  • Environment variables, both plain and secure. Values live locally; the secure map stores key names only, with the values keyed out to OS credential storage. There is no .daintree/env file.
  • Shell program path and default working directory, the machine-specific terminal fields.
  • Dev server detection state: auto-detected and dismissed flags.
  • Project icon (SVG), the default worktree recipe, and the default worktree mode.
  • Forge remote overrides, branch prefix settings, preferred editor and image viewer, command overrides, and git init defaults.
  • Notification overrides, saved fleet scopes, resource environments, browser panel allowed hosts, and the project's MCP settings (tier, confirmation policy and agent exposure).

Everything marked shareable is written: run commands, excluded paths, dev server command and load timeout, Turbopack flag, CopyTree settings, worktree path pattern, and the shareable terminal settings (shell arguments and scrollback). The terminal's shell path and default working directory stay local, because both are absolute paths that differ per machine. The full field reference is on Project Settings.

Warning

You may see .daintree/*.local.json in the .gitignore snippet Daintree offers, and in the Minimal .gitignore template. Nothing in Daintree reads or writes such a file. It is an ignore-only convention kept so a future machine-local override can't be committed by accident. Don't build a workflow around it.

.gitignore guidance

The enable confirmation panel shows a snippet you can copy. Daintree never modifies .gitignore on its own.

project.json, settings.json, recipes/ and presets/ are intended for sharing; review their contents and script behavior before committing them. The line worth adding is:

.daintree/*.local.json

If your project uses plugins with project-scoped storage, or Remote Compute, consider ignoring the generated pieces too:

.daintree/plugin-storage/
.daintree/daintree-remote

Worktree lifecycle scripts

.daintree/config.json defines shell commands that run automatically when worktrees are created or deleted: npm install, seeding a database, tearing down containers. Once approved, lifecycle scripts run for every worktree without asking again (see Approving repository commands). To launch specific agents or panels conditionally, use Recipes instead.

Create the file by hand. It is independent of the in-repository settings toggle, and Daintree never writes it:

{
  "setup": [
    "npm install",
    "cp .env.example .env"
  ],
  "teardown": [
    "docker compose down"
  ]
}

Setup commands run asynchronously after a new worktree is created, with the worktree root as the working directory. You can switch to the worktree and use it immediately, but tools that depend on setup finishing (npm-installed CLIs, for instance) won't be there until the spinner clears. Commands run in sequence; if one fails, the rest are skipped. Teardown commands run before git worktree remove, and teardown failures are logged but never block deletion.

Cloning ignored directories

A setup step that only reinstalls dependencies can often be replaced. cloneIgnored names gitignored directories, such as node_modules, .venv or target. When Daintree creates a worktree, it clones them from the main checkout into it, copy-on-write, after copying the .worktreeinclude files and before setup runs. The list comes from whichever config.json wins the priority order. A worktree created outside Daintree gets no clones.

{
  "cloneIgnored": ["node_modules"],
  "setup": ["npm install"]
}

A copy-on-write clone shares the original's disk blocks until either side changes a file, so a large dependency tree arrives in the new worktree quickly and takes almost no extra space. Each entry is a path relative to the project root, and it is cloned only when:

  • it is a real directory in the main checkout, and Git ignores it there and in the new worktree, so a tracked or merely untracked path never qualifies;
  • nothing already exists at that path in the new worktree, and its parent is an existing folder inside the worktree;
  • the main checkout and the worktree are on one volume that supports copy-on-write: APFS on macOS, or a Linux filesystem with reflinks, such as Btrfs or XFS, with a cp that supports --reflink=always.

Anything else is skipped, never replaced by a full copy. Windows always skips. A skip doesn't fail setup: the setup commands still run, which is why keeping the install there is a sensible fallback. All of a worktree's clones share a 60-second budget of their own, separate from setup's. cloneIgnored runs no commands from the repository, so a repository file's entries need no approval, and a malformed cloneIgnored is ignored on its own without costing the file its other keys.

Approving repository commands

A config.json inside the repository (at the project root or in a worktree) can come from any branch, including a pull request from someone you have never met, so its commands don't run until you approve them. The first time a worktree needs them, setup stops and the worktree card reads "Setup is waiting for you to approve its commands" (or "Repository commands need your approval to run") with a Review commands button.

The Approve repository commands? dialog lists every command the file would run, grouped by phase, including resource provision, teardown, status and connect commands, warns that they run with your account, and approves with Approve and run setup (or Approve commands). Approval is per project and covers those exact command lines, not the scripts they call. Any change to them, on any branch, asks again, while a new worktree carrying the same commands does not. Approvals are kept in Daintree's own app data, not in the repository.

Until you approve, nothing waits on you: setup is left pending, a teardown is skipped and the delete goes ahead, and a resource environment's connect command is withheld. The user-level file in ~/.daintree/projects/ is yours, so its commands run without approval.

Script priority order

Daintree checks three locations for config.json:

  1. ~/.daintree/projects/<sanitized-root>/config.json: user-level override, machine-local, not in the repo. <sanitized-root> is the absolute project path with the characters / \ : * ? " < > | replaced by underscores.
  2. <worktree-path>/.daintree/config.json: worktree-level.
  3. <project-root>/.daintree/config.json: the main repo config, shared with the team.
Warning

The first existing, valid file wins completely. This is not a merge. A worktree-level config.json that defines only setup silently discards the repo-level teardown, and a user-level file that defines only setup discards both of the others entirely.

The user-level location is the place for machine-specific steps (activating a local virtualenv, say) without touching the shared repo config.

Resource environments

The same file carries Remote Compute configuration under resource (singular) or resources (a map keyed by environment id). Resolution runs in this order: resources[<environmentId>], then resources["default"], then the first entry in resources, then resource.

Resource environments read a separate, two-candidate chain for settings.json: the user-level file first, then the project root. There is no worktree level for that one.

Config validation

If a config.json is invalid JSON or doesn't match the schema, Daintree logs a warning, skips it, and tries the next location in the chain. A malformed cloneIgnored is the exception: it is dropped, and the rest of the file still applies. The recognized top-level keys are setup, teardown and cloneIgnored (string arrays), resource and resources, and attachments: named resources one worktree can hold at a time, each with attach and detach commands and an optional status command. Attachments are read from the main checkout's config.json or your user-level file, never from a worktree's copy, and their commands go through the same approval as the rest. If all three levels are missing or invalid, no lifecycle scripts run.

When scripts don't run as expected, first check the worktree card for a pending approval, then check the log file (Settings > Troubleshooting > Application logs > Open log file) for config parse warnings.

Template variables

Commands go through a substitution pass before they run. This is a separate mechanism from the environment variables below. It rewrites the command string itself:

VariableExpands to
{{branch}}The branch name, when known
{{worktree_path}}Absolute path to the worktree
{{worktree_name}}The worktree name
{{project_root}}Absolute path to the main repository root
{{endpoint}}The active resource environment's endpoint, when there is one
{parent-dir}Parent directory of the repository
{base-folder} / {repo-name}The repository folder name
{branch-slug}Sanitized branch name

Substituted values are shell-escaped, so a branch name with a space or a quote in it can't break out of the command.

Injected environment variables

Daintree sets these on every lifecycle command:

VariableValue
DAINTREE_WORKTREE_PATHAbsolute path to the worktree directory
DAINTREE_PROJECT_ROOTAbsolute path to the main repository root
DAINTREE_WORKTREE_NAMEThe worktree name
DAINTREE_BRANCHThe branch name, only when it is known
DAINTREE_RESOURCE_PROVIDERRemote Compute provider id, when a resource environment is active
DAINTREE_RESOURCE_ENDPOINTThe resource endpoint, when there is one
DAINTREE_RESOURCE_STATUSOutput of the resource's last status command
CItrue
NONINTERACTIVE1
GIT_TERMINAL_PROMPT0
DEBIAN_FRONTENDnoninteractive

Global and project environment variables are injected too. The project value wins over the global value; the merged set is applied first, and the DAINTREE_* set above overrides them on a name collision. Set them in Settings > Environment or Project Settings > Variables.

The script environment is an allowlist

Warning

Lifecycle scripts do not inherit your shell environment. They run under an allowlist that is built from scratch on every platform, and anything not on it is dropped.

PlatformVariables that pass through
macOS and LinuxPATH, HOME, LANG, LANGUAGE
WindowsPATH, SYSTEMROOT, USERPROFILE, TEMP, TMP, PATHEXT, LANG, LANGUAGE
EverywhereAnything prefixed LC_ or DAINTREE_, plus your project's env vars and the injected set above

Everything else is gone: proxy variables, NVM_DIR, VOLTA_HOME, PYENV_ROOT, the XDG_* directories, and, deliberately, the loader-injection variables LD_PRELOAD, DYLD_INSERT_LIBRARIES, NODE_OPTIONS and ELECTRON_RUN_AS_NODE. The allowlist is the security boundary: the set of secret variable names is unbounded, so blocking known-bad names would be structurally insufficient. TERM is forced to dumb.

If PATH is somehow absent, Daintree substitutes a fallback, /usr/local/bin:/usr/bin:/bin on POSIX, the system directories on Windows. That fallback is a last resort, not a forced minimal PATH; normally your real PATH is passed through intact.

Commands spawn non-interactively, so do not rely on interactive profile setup from .bashrc or .zshrc. Tools and version-manager shims already reachable through the inherited PATH can work; interactive aliases and shell functions may not. Use explicit executable paths when the inherited path is insufficient.

Timeouts

PhaseBudget
Setup120 seconds, shared across the whole command set
Teardown (normal delete)120 seconds, shared
Teardown (force delete)15 seconds
Resource provision / teardown300 seconds, extendable by a timeouts block inside the resource configuration, with no enforced ceiling

The budget is shared, not per command, and it is checked before each one: a command that would start after the deadline fails with Timed out before running command N: … rather than being launched and killed. On a real timeout Daintree terminates the process group: SIGTERM then SIGKILL after 5 seconds on macOS and Linux, taskkill /F /T on Windows.

Script output

While setup runs, the card shows its lifecycle status. A failed setup offers Retry setup and a Show details disclosure with the captured error and output tail. This is bounded output, not a full persisted setup log. If you need a complete setup transcript, redirect the command to a file:

npm install >> .daintree-setup.log 2>&1

Teardown is different: its output is persisted automatically, which is the more useful case anyway since the worktree directory is about to disappear. Logs land in:

~/.daintree/projects/<sanitized-root>/teardown-logs/<worktree-name>/

Up to 10 logs are kept per worktree, oldest pruned first. Output passes through pattern-based secret redaction, and the tail shown inline is capped at 8 KB with a marker pointing at the full log on disk.

Project Tools in the Repository

A project plugin turns the repository into a small platform for its own workflows: a release checklist, environment dashboard, dataset inspector, or domain-specific operations panel can travel with the code. The plugin directory is independent of the shared-settings toggle. Its code must pass project plugin trust before it runs.

Start with Project Plugins for useful applications, then Building Project Plugins for the directory and build workflow. Project Plugin Surfaces maps where tools appear, and Project Plugin Trust explains approval, changes and instance controls.

New worktrees inherit .daintree/

When Daintree creates a worktree, it copies .daintree/ from the main repo into the new worktree so shared config and lifecycle scripts are available immediately. Existing files in the destination are never overwritten: a worktree that already has a .daintree/config.json keeps it as a worktree-level override.

One consequence follows from the priority order: once a worktree exists, later edits to the repo-level config.json won't reach it, because the copied worktree-level file wins. Delete the worktree's .daintree/config.json if you want it to pick up the updated repo-level scripts.

Gitignored local files such as .env or certificates are a separate mechanism: list them in a .worktreeinclude file at the repository root (not inside .daintree/), and new worktrees copy them in. See Copying local files.