maestrly.
EN ⌄Download free

Projects and Git

A project (workspace) connects conversations to a Git repository on your machine. Git gives each task a visible change set and, when you want it, an isolated worktree. For a quick question or work that needs no repository, a standalone chat is enough.

Chats and projects

The sidebar has Chats, Workspaces, and Bots tabs.

  • Chats → New chat starts a standalone chat without a project. It keeps its working files in a private folder in the app profile, which is not an operating-system sandbox. It starts in the mode you last chose in a standalone chat (Ask the first time) with Ask for approval, and does not inherit any project's instructions, memory, or saved permissions. Maestro, Git review, branch operations, and project memory need a project. Archiving keeps the chat and its files; deleting removes them.
  • Workspaces lists your projects and their conversations. Removing a workspace from the list does not delete the repository on disk.

Add a project

In Workspaces, choose Add workspace to open Add project:

  • Open existing: pick a repository folder. Since 0.24.0, a folder without usable Git history can be initialized on main (Initialize Git in this folder), committing its current files as the Initial commit so worktree conversations start with your files instead of an empty folder. Files ignored by .gitignore or global Git excludes, dependency and cache folders (node_modules, .venv, venv, __pycache__), .DS_Store and Thumbs.db, likely secrets (such as .env and key files), files of 50 MB or more, and folders with their own Git repository stay out of the commit, untouched in your folder.
  • Create new: a new folder in a Parent folder, with Git, a README, and an initial commit.
  • Clone Git repository: an HTTPS, SSH, or file URL, or a local path. Authentication uses your Git credential helper or SSH agent; URLs with embedded credentials are rejected. Nothing is pushed automatically.

Before starting work, confirm that you understand the working tree's existing changes, that build and test dependencies are available, and that secrets and generated files are covered by ignore rules. Repositories stay at their own paths. Use Default branch… in the workspace menu to set the base for new worktrees.

Create or clone a project from a chat

Since 0.15.0, the project you are discussing does not have to exist yet. First choose a Projects folder in Settings → Execution; it is also the default parent folder in Add project. Then ask, for example "Clone acme/api from GitHub and start implementing the export endpoint" or "Create a new project called Atlas with a repository on GitHub and start the MVP."

The agent first looks for a matching workspace. If there is none, it can find the repository with your signed-in GitHub CLI (gh), clone it, or create an empty project with a README and an initial commit. The project is registered as a workspace, and the agent can start a conversation in it. A New project card shows the source, the folder, the clone progress, and Show in sidebar.

  • Without a projects folder nothing is created, and the card offers Set projects folder (browsing this computer's folders, or the folders of a paired computer or server workspaces environment).
  • Git URLs are cloned with your own Git credentials; GitHub owner/name uses the protocol configured in gh.
  • A GitHub repository is created only when you ask for one. It is private unless you want it public, and a public one is created only after you confirm in the chat. An existing repository with the same name is never reused or overwritten.
  • Projects are created only in turns you start, never by subagents, bots, automations, or because a file, card, or web page says so. One message can create up to 10. Repeating the request reports the existing project instead of cloning again.

Choose where a conversation works

In New conversation, pick a branch (New branch from a base in Create from, or Existing branch; Fetch branches brings in branches created on the remote) and a Work mode:

  • Worktree: an isolated folder outside the repository, in the app data, on its own branch. It does not touch your main checkout. Choose it for parallel or automated work, or anything you want to review first.
  • Local: uses the repository folder itself, shared with your editor. If the branch must change, Maestrly shows a preview first and preserves your local changes. Choose it for supervised work.

Move to isolated branch… moves a local conversation and its current work to a new branch and worktree, after a preview. Deleting a conversation also deletes the worktree and branch it created, so deliver what you want to keep first.

Hand work from a chat to a project

Since 0.14.0, a standalone chat can send a development plan to a registered workspace when you ask explicitly, such as "Send this plan for development in workspace Example, on a new branch feat/example from main." The agent finds the workspace, and asks when the name is ambiguous. A target workspace always gets a new worktree. The branch starts from the workspace's default branch unless you name a base, and only locally available references are used; nothing is fetched. The model, effort, and Fast settings carry over unless you say otherwise. Retrying reuses the same destination conversation, and an Ask chat stays read-only. Project chats can do the same; see Maestro, agents, and skills for starting several conversations at once.

Work in parallel

  • Give each automated conversation its own worktree. Avoid two automated conversations in the same checkout.
  • New conversation from this one creates a sibling that shares the same worktree, Git index, and notes. Split the work to avoid conflicts.
  • For work across repositories, check two or more repositories in New conversation. The Branch (created in all repos) is created in each one, with one worktree per repository. Review each diff separately.
  • Worktrees isolate files, but databases, ports, credentials, and cloud environments can still collide.
  • Open chat in new window keeps a conversation open beside others, including on another monitor, while its work continues.

Projects on your bot server

A bot on your bot server can start conversations in projects you grant it, and you can run whole workspaces on the server itself (both Experimental). See Bots and Remote workspaces.

Review the result

The drawer's Review tab shows the Diff (local branch against its base, or the pull request), plus PR, Checks, and Comments when the branch has a pull request on GitHub. Pull request data needs the GitHub CLI, signed in with gh auth login. Before delivery:

  1. inspect the changed and untracked files;
  2. compare the diff with the requested scope;
  3. run focused tests, formatting, type checks, or builds;
  4. check for secrets, accidental generated files, and unrelated edits;
  5. commit with a message that describes the verified outcome.

Do not merge or deploy only because the agent reports completion. Treat its summary as a result to verify. Resolve conflicts with AI merges the base into a conflicting pull request branch, commits, and publishes the branch; use it only when you want that push.

Clean up safely

Merge, cherry-pick, or otherwise deliver the reviewed branch through your normal Git process. Delete a conversation, which removes its worktree and branch, only after its wanted changes are committed and preserved elsewhere. If you abandon a task, inspect its uncommitted changes before discarding anything.

Since 0.20.0, archiving or deleting a conversation ends the processes its terminals and bash commands left running, such as a development server sent to the background, and deleting it also removes the temporary files its tools wrote. Only processes Maestrly can tie to that conversation are ended; programs that detach on purpose, such as setsid, docker compose up -d, tmux, and screen, keep running.

Next: Usage and costs.