Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

4.1 KB
Raw Blame

id: worktrees title: Working in an isolated git worktree summary: Start a session in an isolated git worktree (Branch | worktree control in the new-session view) so its changes stay on their own branch and folder; what happens on archive/delete and how to restore.

A session can run inside its own git worktree — a separate working copy of the same repository on its own branch — so the agent's edits don't mix with your main checkout.

Opting in:

  • In the new-session view, pick a project that is a git repository. A combined control appears next to the project picker: the left half shows the Branch (the source branch, defaulting to the repo's current branch; click it to search and choose another), and the right half is a worktree checkbox. Tick worktree to use isolation.
  • The checkbox is off by default. Cindy remembers your last explicit choice for new sessions on that computer.
  • The worktree is created when you send the first message. While it's being created, an overlay shows Creating worktree · input disabled and the composer unlocks automatically when it's ready.
  • Next to the branch, a refresh button can pull the latest commits for the selected branch from its remote before you start.

Where it goes:

  • Folder: <repo>/.cindy-worktrees/<auto-generated-name>/. Worktrees created by older versions under .xdt-worktrees/ remain supported.
  • Branch: cindy/<auto-generated-name>, created from the source branch you picked. Older branches under xdt/ remain supported.
  • Untracked local files (such as .env) aren't in a new worktree by default. List them in a .worktreeinclude file (.gitignore syntax) at the repo root and Cindy copies matching untracked files into each new worktree.

Lifecycle:

  • The worktree survives app restarts, /clear, and reconnecting.
  • When you archive or delete the session, Cindy removes the worktree folder but keeps the branch, so you can still merge or cherry-pick from it. Uncommitted changes and new files are first saved as a git snapshot (the confirmation dialog warns you when there are any). Files ignored by .gitignore (dependencies like node_modules, build output, caches) and git repositories cloned inside the worktree are not kept.
  • Removal is skipped if the folder contains a .worktree-keep file or another live session is still using it.
  • Restoring: when you unarchive the session and send a message, Cindy recreates the worktree from the kept branch and re-applies the snapshot automatically. If you open a session whose worktree is missing, a banner offers Restore worktree (or Apply changes if only the snapshot is pending).
  • Settings > Storage > Worktree cleanup lists worktrees still awaiting cleanup, with Retry cleanup and Keep directory.

When the control doesn't appear:

  • The control is hidden when Git isn't installed, the chosen folder isn't a git repository, or it's already inside a worktree (no nesting). It's also hidden for projectless chats.
  • While Cindy is still detecting the folder, or detection failed, the checkbox is disabled and its tooltip explains why.

Errors (shown if creation fails):

  • Cannot access worktree directory (permissions), git-crypt repository is not unlocked, Dubious git repository ownership (safe.directory), git-lfs sync failed, Current directory is not a git repository, git not detected. Each comes with a suggested fix.

Other places that use worktrees:

  • Automations can run in a New worktree session (see the Scheduling automations topic), collaboration Workers can get their own worktree (Create a worktree for this Worker), and importing a shared session offers Create in a worktree.
  • In Sidebar settings → Session info, tick worktree to show each session's worktree name; click it to open the folder.
  • A session whose working directory is a worktree can't be moved to another project yet.

Notes:

  • The agent works inside the worktree folder automatically; you don't need to switch directories.
  • Because the branch outlives the worktree, you can always find the agent's work with git branch --list 'cindy/*' 'xdt/*'.
  • Worktrees don't affect sessions that don't use them.