Projects
What a Daintree project is, how to open one from any folder, git-backed versus lightweight workspaces, and moving or renaming a project without losing your work.
What a project is
A project in Daintree is a folder on your machine. It does not have to be a Git repository. Open any directory and Daintree adopts it as a lightweight workspace: terminals, agents, recipes and the file browser all work, and Daintree never writes anything into the folder unless you ask it to.
Git is what unlocks the review-first half of the habitat. Worktrees, the Review Hub, diffs and Code Forge all need a repository, so they stay unavailable in a lightweight workspace until you initialize one. That upgrade is a two-option choice, not a forced walkthrough.
Everything Daintree knows about a project (settings, panel layout, recipes, secure environment variables) is stored per project in Daintree's own app data directory, keyed by a stable project id. That id is minted once, when the project is first registered, and never changes afterwards; a project keeps its identity across a folder move. If you want part of that configuration to travel with the repository instead, see The .daintree Directory.
Opening a project
From inside Daintree:
- File > Open Directory… (Command-O Control-O Control-O ) to pick a folder.
- File > Open Recent for a project you have opened before.
- File > Clone Repository… to pull a repository down first (see Cloning a repository).
- The project switcher, which carries Add Project…, Clone Repository… and Create New Folder… at the bottom of its palette.
- The Welcome Screen's quick actions: Open folder, Create project, Clone repository, Launch agent.
From the operating system
Daintree also registers folder-level entry points outside the app, so you can start from wherever you already are.
- Drop a folder on the Dock icon to open it as a project.
- Right-click a folder in Finder and choose Open in Daintree. This is a Finder Quick Action and is installed on demand: run Terminal > Install "Open in Daintree" Quick Action once, and Daintree copies the workflow into
~/Library/Services. The same menu has a Remove counterpart. - Terminal > Install Daintree Command Line Tool installs the
daintreecommand, sodaintree .opens the current directory.
- Right-click a folder in Explorer, or right-click empty space inside a folder, and choose Open in Daintree. The installer registers both verbs per user, so no elevation is involved.
- Double-clicking a
.dntrplugin archive opens Daintree on the plugin installer rather than a project.
- Daintree declares the
inode/directoryMIME type, so on desktops that honor it (GNOME and Nautilus, for example) it appears under Open With for any folder. - Terminal > Install Daintree Command Line Tool installs the
daintreecommand, sodaintree .opens the current directory.
A launch that names something specific (a CLI path, a dropped folder, an "Open in Daintree" invocation) opens exactly that, in one window. A plain cold launch with nothing named restores your previous set of windows instead (see Windows).
Git-backed and lightweight workspaces
When you open a folder that has no repository, Daintree asks a single question rather than starting a wizard. The dialog is titled Open '<folder>'? and offers two buttons:
- Open without git: the folder is registered as a lightweight workspace and opens immediately. Nothing on disk changes.
- Initialize repository: moves on to git setup, described below.
What a lightweight workspace can do
| Works without a repository | Needs git init first |
|---|---|
| Terminals and every agent | Worktrees |
| Recipes | The Review Hub and diff review |
| The file browser and file viewer | Code Forge: issues, PRs, CI status |
| Panels, the dock and the panel grid | Project Pulse |
A lightweight workspace also never gets a .daintree/ directory: Daintree deliberately skips writing project identity into a folder it was told not to modify.
Upgrading with git init
You can initialize at any time from inside the workspace: the bottom of the sidebar carries a quiet Initialize repository button, captioned "Terminals, agents, and recipes work without one". It skips the choice step and goes straight to git setup.
The git setup dialog asks for four things:
- Project name and emoji, seeded from the folder name (Daintree suggests an emoji based on it).
- A
.gitignoretemplate. Eleven options, defaulting to Minimal. - Whether to create an initial commit, on by default.
- The initial commit message, defaulting to
Initial commit.
The template list is:
| Template | Covers |
|---|---|
| Minimal (default) | OS junk, editor state, secrets and key material, logs, and AI-agent local state |
| Node / TypeScript | node_modules, build output, caches |
| Python | __pycache__, virtualenvs, tooling caches |
| Rust | target/, rustfmt backups |
| Go | binaries, test output, workspace files |
| Java / JVM | Gradle and Maven output, class files |
| PHP / Laravel | vendor/, storage, compiled assets |
| Ruby on Rails | logs, tmp, bundler, credentials keys |
| C# / .NET | bin/, obj/, user files |
| Static web | build output, tool caches |
| None | Don't create a .gitignore at all |
Minimal is the baseline every language template is composed on top of, which is why it is the default: a Rust project gets the Rust layer and the secrets, OS and editor coverage. Progress streams into the dialog as it runs, and the dialog closes itself once initialization succeeds.
Initializing from Daintree creates a repository and, optionally, stages everything and makes a first commit. No remote is added.
An existing .gitignore is never overwritten. Daintree keeps it and compares it against the template you picked, reporting either "covers all template entries" or how many entries are missing so you can review it for secrets yourself. If your git identity isn't configured, the repository is still initialized and the dialog tells you exactly which two git config commands to run before committing.
Naming a project
A project carries a display name and an emoji, and both are set at creation rather than being derived from the folder forever. Create New Folder… puts the emoji picker next to the folder-name field, and the git setup dialog carries the same pair. Whatever you choose there is what appears in the switcher, the sidebar, and the window title.
Both can be changed later from Project Settings > General, and the Move or rename project dialog can change the display name at the same time as the folder.
Cloning a repository
If a repository isn't on your machine yet, clone it from Daintree. This runs git clone and registers the result as a project automatically. The clone dialog is reachable from File > Clone Repository…, the project switcher, the Welcome Screen, and the action palette.
It has four fields:
- Repository URL: an HTTPS URL (
https://github.com/user/repo.git), an SSH URL (git@github.com:user/repo.git), or GitHub shorthand (owner/repo). - Parent Directory: where the cloned folder should go.
- Folder Name: derived from the URL with any
.gitsuffix stripped, editable. - Shallow Clone: passes
--depth 1. Useful on large repositories where you don't need the full history.
The owner/repo shorthand expands to https://github.com/owner/repo. For anything hosted elsewhere (GitLab, Bitbucket, a self-hosted forge), use the full HTTPS or SSH URL.
A progress log streams the clone output as it runs, and you can cancel at any point; Daintree cleans up the partially cloned files. Authentication uses your system Git credentials: HTTPS clones go through your credential helper (macOS Keychain, Windows Credential Manager, and so on) and SSH clones use your SSH agent and the keys in ~/.ssh. If authentication fails, the clone stops immediately rather than blocking on a prompt you cannot answer.
Moving or renaming a project
A project's folder can be moved or renamed from inside Daintree, and the open workspace follows it. Reach the dialog from Project Settings, from Move or rename project… in the switcher's row context menu, or from the recovery path when a folder has gone missing.
There are two modes:
- Move: Daintree performs the rename itself. Same volume only; a cross-volume destination is refused rather than silently copied.
- Reattach: the folder was already moved outside Daintree, and you point Daintree at where it is now. The dialog asks "Where is the folder now?" and shows the original location above it.
Before you commit, the dialog previews the blast radius: the old and new paths, how many panels will have their stored paths rewritten, how many terminals will be gracefully stopped ("they restart at the new location"), and which linked worktrees will be repaired. It also breaks down what happens to each running agent's conversation, riskiest first:
| Tier | What it means |
|---|---|
| Conversation can't be resumed | This agent has no way to resume the conversation after a move. |
| Provider migration required | The provider can't resume this conversation at the new path. |
| Resume after move unverified | Resuming this conversation after a move isn't confirmed either way. |
| Conversation stays with the folder | It resumes from the project folder, which is moving with it. |
| Resume supported | Expected to resume automatically at the new location. |
The window's renderer and its terminal instances are never torn down, so the move is not a reload. A few conditions block it outright and disable the confirm button: a relocation already running for this project, a destination that another project is registered at, a reattach target that doesn't exist, a cross-volume move, and a running Daintree Assistant: "Stop the Daintree Assistant for this project before moving it."
When a folder goes missing
If a project's directory is no longer where Daintree left it, the project's status becomes missing, its switcher row reads Directory not found, and the row context menu offers Locate moved project, which opens the reattach flow described above.
A related case: a project recorded as git-backed whose .git has since disappeared. Daintree refuses to activate it while it still claims worktree capability, and routes you to the same choice dialog you saw when first opening a non-repo folder, so giving up the project's git identity stays an explicit decision. That routing covers switching from the switcher and back/forward navigation, not just path-based entry points. The check is deliberately timid: only a proven-absent repository escalates. A dead mount, a permissions blip or a missing git binary leaves the project alone.
Folder-open failures in general report what actually went wrong rather than surfacing raw git output.
Project status
Each project sits in one of four states:
| Status | Meaning |
|---|---|
| Active | On screen in a window. |
| Background | Open with running processes, but not displayed. This is what lets you switch away without killing terminals. |
| Closed | No running processes. Fully dormant. |
| Missing | The directory is no longer at the stored path. |
Closing a project asks whether to kill its terminals or leave them running in the background. Reclaiming a background project's memory without closing it is a separate action. See Freeing memory.
Windows
Daintree is multi-window, and each window holds its own project.
- File > New Window (Option-Shift-Command-N Control-Alt-Shift-N Control-Alt-Shift-N ) lands on the Welcome Screen rather than reopening the last project, so you can pick a different project (or the same one) without a forced reload.
- Open in new window in the switcher's context menu opens the chosen project in its own window directly.
- A relaunch restores every window you had open, each on the project it was showing, ordered most-recently-focused first and capped at eight. A window that was sitting on the project picker restores as a picker window. Safe mode and an unresolved crash deliberately skip restore and open one window instead, so a bad launch can't become a crash loop.
- Each window's title names its active project, prefixed with that window's waiting-agent count when there is one:
(2) my-project. The app name is not appended, because the Dock already groups every window under one icon and repeating it costs the space that tells the windows apart.
Welcome Screen
With no project open, a window shows the Welcome Screen: your projects listed in the same order the switcher's residual band uses, plus quick actions for Open folder, Create project, Clone repository and Launch agent. New installs also get a short getting-started checklist, dismissible once you're comfortable.
Per-project settings
Each project keeps its own configuration: run commands, dev server command, CopyTree settings, environment variables, worktree path pattern, terminal settings, the default worktree recipe, notification overrides. Reach it from File > Project Settings… or the switcher's Project Settings… button. The full field reference, including which values are project-scoped versus inherited from Global, is on Project Settings.
Some of that configuration can be committed and shared with your team. That is what the .daintree/ directory is for.
Where to go next
- The Project Switcher: bands, row status, sorting, the context menu, keyboard model, and how warm and cold switching behave.
- Scratch Workspaces: throwaway, app-managed workspaces for one-off tasks.
- Project Pulse: the activity strip on the empty panel grid.
- The .daintree Directory: team-shared project config, presets and worktree lifecycle scripts.
- Worktrees: creating, comparing and deleting worktrees, worktree cards, and path patterns.