Skip to main content

Projects

What a Daintree project is, how to open one from any folder, git-backed versus lightweight workspaces, moving or renaming a project without losing your work, and how projects map to windows and come back on relaunch.

Updated
Reviewed

What a project is

A project in Daintree is a folder, on this machine or on a remote host you have added. It does not have to be a Git repository. A folder without Git can be opened as a lightweight workspace: terminals, agents, recipes and the file browser work without initializing a repository. A folder that already has Git opens with repository capabilities.

Git is what unlocks isolated parallel work and the changes you can check. 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 Project… (Command-O Control-O Control-O ) to pick a folder, or File > Open Project in New Window… to open it in a window of its own.
  • File > Open Recent for a project you have opened before. Cmd-click an entry (Ctrl-click on Windows and Linux) to open it in a new window.
  • File > Clone Repository… to pull a repository down first (see Cloning a repository).
  • The project switcher, which carries Open project…, Clone repository… and Create new folder… at the bottom of its palette.
  • The Welcome Screen's quick actions: Open project (with an Open in new window… button beside it), Create project and Clone repository.

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 > Open With and choose Daintree.
  • 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 daintree command, so daintree . 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.
  • The installer normally puts the daintree command on your PATH, so daintree . opens the current directory. The Store build doesn't.
  • Double-clicking a .dntr plugin archive opens Daintree on the plugin installer rather than a project.
  • Daintree declares the inode/directory MIME 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 daintree command, so daintree . 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). While Daintree is already running, a folder opened from outside it fills an empty window or opens a new one; by default it never replaces the project in a window you are using (see Opening folders in a new window).

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>'?, says "This folder isn't a git repository.", and states the cost of each answer beside its name:

  • Open without git: the folder is registered as a lightweight workspace and opens immediately. "Opening won't change anything in this folder."
  • Initialize repository: moves on to a preview of the git setup, described below. "Nothing changes until you confirm."

Cancel backs out without registering anything.

Opening a folder that is not a repository is a two-option choice, not a walkthrough

What a lightweight workspace can do

Works without a repositoryNeeds git init first
Terminals and every agentWorktrees
RecipesThe Review Hub and diff review
The file browser and file viewerCode Forge: issues, PRs, CI status
Panels, the dock and the panel gridProject Pulse

In place of worktree cards, the sidebar shows one row for the folder itself. Its More actions button (and the same menu on right-click) offers Launch (agents, a terminal, the browser or a dev preview, all in the folder), Open (Browse files, Open in editor, reveal in your file manager), Copy (Full context of the folder, or its Path) and Recipes for the project's recipes that aren't tied to a worktree. Git, review and session rows are left out because they need a worktree.

Daintree skips automatically writing repository identity files for a lightweight workspace. This does not prevent your commands, recipes or project tools from creating files there.

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, titled Set up repository, asks for four things:

  • Name and emoji, seeded from the folder name (Daintree suggests an emoji based on it).
  • Gitignore: a .gitignore template. Eleven options, defaulting to Minimal.
  • Commit: Create initial commit, on by default.
  • Message: the initial commit message, defaulting to Initial commit. It is only shown while the commit box is ticked.

A line under the form states what the button will write, for example "Creates a Git repository in this folder, adds a .gitignore, commits everything in it."

The template list is:

TemplateCovers
Minimal (default)OS junk, editor state, secrets and key material, logs, and AI-agent local state
Node / TypeScriptnode_modules, build output, caches
Python__pycache__, virtualenvs, tooling caches
Rusttarget/, rustfmt backups
Gobinaries, test output, workspace files
Java / JVMGradle and Maven output, class files
PHP / Laravelvendor/, storage, compiled assets
Ruby on Railslogs, tmp, bundler, credentials keys
C# / .NETbin/, obj/, user files
Static webbuild output, tool caches
NoneDon'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. On success it reads Repository initialized and opens the project on its own two seconds later, or straight away with Open project.

Note

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 an Initial commit skipped notice gives you the two git config commands to run (each with a copy button) before you retry.

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. The Create project folder dialog (from Create new folder…) and the clone dialog put the emoji picker next to the 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.

Right-click the toolbar’s project pill and choose Edit name and icon… to change the name and emoji. You can also change them under Project Settings > General > Project identity, 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 two sections:

  • Repository: the URL, either HTTPS (https://github.com/user/repo.git) or SSH (git@github.com:user/repo.git), and a Shallow clone checkbox ("Latest commit only, limits history"), which passes --depth 1. Useful on large repositories where you don't need the full history.
  • Destination: the Location the cloned folder goes in, its Name (derived from the URL with any .git suffix stripped, editable, with an emoji picker beside it), and Open in: This window or New window.

The footer shows the full path it clones into ("Clones into …") beside the Clone button.

Tip

An owner/repo shorthand only expands when exactly one forge provider is installed, because with two there is no telling which host it means. With both built-in providers (GitHub and GitLab) enabled, the field asks for a full repository URL.

A progress log streams the clone output while it runs. Stop clone cancels the active clone and attempts to clean up its partial folder. A cleanup failure shows Partial clone not removed with the remaining path so you can remove it after releasing any file locks. On success, Repository cloned opens the project on its own two seconds later, or straight away with Open project (Open in new window if you chose a new window).

When you are signed in to the matching forge in Code Forge, Daintree clones with that sign-in. Otherwise 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, and for a recognized forge the error offers Sign in to <provider>.

To clone onto a remote host instead, use Add project… on the host's card in the Hosts overview, or bring a project you already have here with Continue this branch on…. Either way the host clones with its own Git credentials; this machine's credentials are never copied, and anything pushed or sent from here happens only when you choose it in the dialog.

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.

Use Move when Daintree should rename the folder, or Reattach when you moved it elsewhere yourself. The preview lists path changes, terminals to stop and each agent's resume support before you confirm. See the relocation preview and limits for the full flow.

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, with a recovery action where one fits: Remove from recent, Choose another folder or Try again.

Project status

Each project sits in one of four states:

StatusMeaning
ActiveOn screen in a window.
BackgroundOpen with running processes, but not displayed. This is what lets you switch away without killing terminals.
ClosedNo running processes. Fully dormant.
MissingThe directory is no longer at the stored path.

Switching away from a project is how you leave it running in the background. Close project (on the current project's row in the switcher) is different: its Close '<project>'? confirmation warns that "All running processes will be terminated" when anything is running, then stops them and returns the window to the Welcome Screen. The project stays in your list. To stop a project's processes but keep its layout and attempt supported conversation resume when you reopen it, use Sleep project instead. See Freeing memory.

Windows

Daintree is multi-window, and each window holds its own project. A project is live in only one window at a time: two windows on one project would attach to the same terminals and resize one shell from two places. Opening a project that another window already has brings that window forward instead, and picking one another window holds in the background switches that window to it.

Window position and size are saved under the project that window is showing. Restore uses that project's own saved bounds where the window manager allows it; a window without a usable saved position is offset from other open windows when there is room. See the Linux release changes.

  • 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 without a forced reload.
  • Explicit new-window opens: File > Open Project in New Window…, a Cmd-click (Ctrl-click on Windows and Linux) in Open Recent, the Welcome Screen's Open in new window…, Open in: New window in the clone and create-folder dialogs, and Open in new window or Command-Enter Control-Enter Control-Enter in the switcher. The Open project in new window action ships unbound; give it a key in Settings > Keyboard Shortcuts if you use it often.
  • 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. The focused window opens first; the rest follow one at a time and appear without taking focus. See Restoring live projects for the background projects that come back with them.
  • After a crash, restoring the session (from the recovery dialog, or automatically) brings the whole window set back too. Safe mode and repeated crashes deliberately open one window instead, so a bad launch can't become a crash loop. See Crash Recovery.
  • 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. A window on a remote host adds the host's name after the project's.

Opening folders in a new window

Settings > General > Overview > Opening folders > Open folders in a new window decides where a folder goes when you open it. Switching between projects in the switcher isn't affected.

ChoiceWhat happens
Only from outside Daintree (default)Folders opened from your file manager, the Dock or the command line get an empty window or a new one; folders picked in Daintree use the current window.
AlwaysEvery folder you open gets a window of its own.
NeverEvery folder you open replaces the current window's project.

Restoring live projects

A relaunch brings back more than the project each window was showing. Every project that was live in a window, whether warm in its cache or running agents after its view had been evicted, is restored in the background, up to eight per window. Each one boots unseen, one at a time across the app, most-recently-used first, and respawns its agents into their saved sessions, so you don't have to click each project awake in the switcher. Restores stop at the Cached project views cap and back off under memory pressure; a project left out simply comes back, agents and all, the first time you open it.

This is Settings > General > Overview > Startup > Restore live projects ("Bring back every project that was running, not just the one each window was showing"), on by default. Turn it off to bring back only the project each window was showing.

Once you have added a remote host, each window is also on exactly one machine: this one, or a host. The host chip beside the project name says which, and windows on different machines sit side by side like any others. A relaunch tries to reopen a window that was on a host on that host and project; if the host can't be reached, the window opens on this machine with a Retry. See Switch Between Hosts.

Welcome Screen

With no project open, a window shows the Welcome Screen: up to five of your projects under Your projects, in the order the switcher's Other projects band uses, plus quick actions for Open project (with Open in new window… beside it), Create project and Clone repository. A first run shows "Welcome to Daintree" with a link to the tour instead of the list. 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…, the switcher's Project settings… row, or Project settings… on the toolbar project pill's right-click menu. 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.
  • Remote Hosts: run a window's projects, terminals and agents on another Mac or Linux machine over your own SSH.

To make a repository carry its own dashboards, release tools and domain workflows, see Project Plugins. These tools live with the project and can turn it into a small platform for the team.