Skip to main content

Open Your First Project

Open a folder as a Daintree project, what changes when it is a Git repository and what still works when it is not, initializing a repository, and opening a folder from your file manager or the command line.

Updated
Reviewed

Opening your first folder

Open a folder from File > Open Project… (Command-O Control-O Control-O ), from Open project on the Welcome Screen, or with the project switcher in the toolbar. To keep the current window as it is, use File > Open Project in New Window… or the small window button on the Welcome Screen's Open project card instead. A project lives in one window at a time, so opening one that another window already has brings that window forward. See Windows for the full set of rules.

A project no longer has to be a Git repository. The picker's title is Open Folder, not "Open Repository", because that requirement is gone. Point Daintree at any folder and it opens as a lightweight workspace.

The code doesn't have to be on this machine, either. If it lives on another Mac or Linux machine you reach over SSH, Remote Hosts runs the project there while the window stays here.

One thing to know before you choose: worktrees are Git worktrees, so running your first parallel task needs a repository. If you are following the getting-started path and the folder has none yet, take Initialize repository here rather than Open without git.

Open the folder now, or set up a repository

The dialog, headed Open 'folder'?, states what each answer costs before you pick it. Open without git has focus when the dialog opens, so a reflexive Enter opens the folder rather than changing anything. Initialize repository only previews the setup on the next screen; nothing is written until you confirm there. Cancel opens nothing.

Open without git

Choose Open without git and you get a workspace immediately. Terminals, agents, recipes, and the file browser all work. Worktrees, review, and diffs stay unavailable until the folder becomes a repository, because there is nothing for them to operate on. The sidebar shows a single Workspace row instead of a worktree list, and there's no branch chip and no Project Pulse. Opening without Git does not initialize a repository. Initialization can create Git metadata and a first commit after you confirm setup. Projects covers the git-optional tier in full, including how to upgrade a workspace later.

Initialize repository

Choose Initialize repository and you land on the Set up repository dialog. It collects three things:

  • Name, with the project's emoji beside it. Both are seeded from the folder name and both are editable. The emoji is how you'll recognize the project in the switcher and the toolbar.
  • Gitignore. Eleven templates, defaulting to Minimal.
  • Commit. A Create initial commit checkbox, on by default, with an editable Message.

The gitignore templates:

TemplateCovers
Minimal (default)OS junk, editor state, secrets, agent 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

Every language template is composed on top of Minimal, so picking Rust still ignores your .env and your editor's scratch files. Initialize repository runs it, with a progress list showing each step (git init, the gitignore, staging, the first commit) as it runs, then Open project takes you in. If the folder already had a .gitignore, Daintree keeps it rather than overwriting it and asks you to review it, since it may not cover your secrets.

Creating a project from scratch

Create project on the Welcome Screen opens Create project folder instead: pick a Location, type a Name, and choose an emoji. The emoji auto-suggests from the name you type until you pick one yourself, and the identity carries through into the git setup dialog. Open in chooses This window or New window up front. Create folder makes the folder, then opens it, offering the same choice as above because a new folder has no repository yet.

Once a folder is open, Daintree scans for existing worktrees and loads any saved state: terminal sessions, panel layout, recipes.

Other ways to open a folder

Every route below lands in the same place, including the choice dialog when the folder isn't a repository.

  • File > Open Recent. Recently opened projects, sorted by when you last opened them, each showing its path so you can tell two api folders apart. Cmd-click an entry (Ctrl-click on Windows and Linux) to open it in a new window.
  • Drop a folder on the macOS Dock icon, or choose Daintree from Finder's Open With. Registered by signed builds only, so a locally built copy won't do it.
  • The daintree command, covered below.

A folder opened from outside Daintree (the Dock, Finder, the daintree command) while it is running fills an empty window or opens a new one; by default it never replaces the project in a window you are using. Settings > General > Overview > Opening folders changes that. See Opening folders in a new window.

"Open in Daintree" in your file manager

macOS won't let an app bundle declare a Finder service, so this one is installed on demand: Terminal > Install "Open in Daintree" Quick Action. That writes an Automator workflow to ~/Library/Services and refreshes the services cache. Right-click any folder in Finder afterwards and Open in Daintree is there.

Terminal > Remove "Open in Daintree" Quick Action takes it back out. Worth knowing: nothing in ~/Library/Services is touched when you delete an application, so without this the Quick Action would outlive Daintree.

The NSIS installer registers the folder verbs for you, under your own user (HKCU) rather than machine-wide, which is what keeps installs and updates from demanding elevation. Right-click a folder, or right-click empty space inside one, and choose Open in Daintree.

Note
Windows 11 files classic context-menu verbs like this one under Show more options. The Microsoft Store build doesn't register them at all.

Daintree claims the inode/directory MIME type in its desktop entry, so on desktops that honor it (GNOME/Nautilus among them) Daintree appears under Open With for a folder. It is not a bespoke context-menu item, and file managers that ignore inode/directory won't show it.

Daintree CLI

The daintree command opens any directory in Daintree straight from your terminal. It works like code . in VS Code. If Daintree is already running, it hands the request to the running app rather than launching a second instance, and the folder opens like any other outside open: in an empty window or a new one, or in the window that already has that project.

Installing the CLI

On macOS and Linux, install the CLI from inside Daintree, via Terminal > Install Daintree Command Line Tool in the menu bar. On Windows, the installer does it.

On macOS, the install creates a symlink at /usr/local/bin/daintree pointing to the bundled CLI script inside the app. That location is on your PATH by default, so the daintree command is available right away in any new terminal session.

If /usr/local/bin isn't writable (rare on a standard setup), the install falls back to ~/.local/bin/daintree, and you may need to add that directory to your PATH yourself.

The installer normally puts the daintree command on your PATH (bin\daintree.cmd in the install folder), so there's no menu item to run. Terminals opened after the install find it. The Microsoft Store build doesn't put it on PATH; open folders with File > Open Project… there instead.

On Windows the command opens a folder and answers --help and --version. --status isn't available there.

The DEB package installs /usr/bin/daintree, pointing to the bundled CLI script. Installing the command through Daintree creates a symlink at /usr/local/bin/daintree, or falls back to ~/.local/bin/daintree if that path isn't writable.

Warning
On some Linux distributions, ~/.local/bin is only added to your PATH when the directory exists at login time. If you get "command not found" after installing, add it to your shell profile and start a new session:
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

AppImage users: Daintree generates a stable wrapper script at ~/.local/share/daintree/daintree-cli.sh during CLI installation. An update that renames the AppImage also updates an installed wrapper. If you move the file elsewhere yourself, re-run Terminal > Install Daintree Command Line Tool to point the wrapper at it.

.deb package users: The CLI script resolves the Daintree binary from its installed location on its own (/opt/Daintree/daintree or your system PATH).

Usage

Once it's installed, open any directory in Daintree from your terminal:

daintree .                  # Open the current directory
daintree ~/projects/my-app  # Open a specific directory
daintree --status           # Check if Daintree is running
daintree --version          # Print the CLI version
daintree --help             # Show usage information
daintree call terminal.list # Call one of Daintree's MCP tools

The bundled CLI script and generated AppImage wrapper support these flags. Each has a short form: -s, -v, -h. The --status flag exits with code 0 when Daintree is running and 1 when it isn't, which is handy for scripting. On macOS and Linux, daintree --status --json prints the same as one JSON object with four fields: version, running, mcpEnabled (null when it can't be told) and mcpPort (null when the MCP server isn't serving).

daintree call and daintree session reach Daintree's MCP tools from scripts and git hooks, on every platform. See Call Daintree From the Command Line. To open a folder named call or session, write it as ./call or ./session.

Tip
The daintree command follows the same folder-opening rules as File > Open Project…. A folder that isn't a repository lands on the same choice: open it as-is, or set git up first.

Source reference: CLI installation and AppImage wrapper, bundled CLI flags, and Gitignore templates.

Linux release changes: installation, updates and desktop integration.