What is a worktree?

git worktree is a git feature that opens one repository as "another folder plus another branch" at the same time. Your usual working folder stays as it is, while you add a second, independent workspace right next to it.

When you start a session in TinyAgentDeck with the "Create in an isolated worktree" toggle ON, a dedicated working folder and a dedicated branch tad/session-<session-id> are created automatically, and claude launches there. This means two or more agents can run in the same repository at once without their files colliding.

When to use it

Turn it ON when you want to run two or more sessions in parallel in the same repository. For a separate project or a one-off task, OFF (launching directly in the project's folder) is plenty.

Starting a session in a worktree

When you turn on "Create in an isolated worktree" under "Start session" in the project dashboard, TinyAgentDeck does the following behind the scenes.

  • Creates the worktree under the app-managed folder (inside ~/Library/Application Support/…/worktrees/) — it never clutters the area around your repository
  • Cuts a dedicated branch tad/session-<session-id>
  • Launches claude with that worktree folder as the current directory

Your usual working folder (the one with main checked out) is never touched. A worktree is an "isolated parallel workspace" you can fold away when you're done.

When you're done

Changes you made inside the worktree only live on that session's branch — they're not in main or in your usual working folder yet. So the trick is to "pull them in" before cleaning up.

Know this first

Uncommitted changes are lost when the worktree is deleted. Even if a deploy script has already shipped them to production, they won't be in git history. The next time you deploy to production from main, the changes can roll back.

That's why the order is always commit → merge into main → clean up.

The easiest way — let Claude do it

The worktree session's terminal has your usual Claude Code in it. You don't need to type git commands yourself. When you're done, just ask, in plain language.

Example (paste it as is).

Commit all the changes in this worktree and merge them into the main branch.
Don't commit any files with secrets, like .env.local.
Tell me when the merge is done.

What Claude does (you just watch).

  1. Checks the changes with git status and leaves out secrets against .gitignore
  2. Commits with a meaningful message
  3. Pulls the worktree's branch into the main checkout
  4. Reports that the merge is done (and flags any conflicts or uncommitted changes)

When the report arrives, check just three things: ① was it committed ② was it merged into main ③ were secrets (.env.local, etc.) left out. If all good, the only thing left for you is to close the card. Since it's committed — no changes left behind — TinyAgentDeck deletes the worktree automatically, and the leftover tad/session-… branch can be removed in one click from the "Orphan worktrees" section.

Why not have Claude clean up too?

The Claude inside the worktree can't delete the worktree it's currently in, or the branch it has checked out (git refuses them as "in use"). So the physical cleanup is the app's job. Claude's role is "commit → merge → report." From there, closing the card finishes it.

Variations on the ask

Don't want to ask every time — write "when you're done, commit and merge into main" in the "first instruction" when you start the session, and it happens automatically at the end.

Want it on GitHub too — add "and run git push origin main once merged" to your ask. Merging into main doesn't push to the remote yet, so add this if you want a backup or shared history (if production is already deployed, the site works without the push).

You work with PRs — instead of going straight into main, ask "commit, push, and open a PR" and Claude will do that.

If you'd rather do it yourself — manual commands

If you want to know what's happening inside, or to go step by step by hand, here are the three steps. Skip them if you're letting Claude handle it.

1

Commit inside the worktree

Run this in the terminal of the session where you did the work.

git status                  # See what changed (check that no secrets slipped in)
git add -A
git commit -m "A clear message"
git branch --show-current   # → note the tad/session-… name (used next)
2

Merge into main

In the terminal of your usual working folder (the one with main checked out, not the worktree), merge the branch name you noted in step 1.

git merge tad/session-…

Even if the same content is already live in production, re-running the deploy script afterward changes nothing (it's idempotent). This brings main and production into sync.

3

Clean up the worktree

Just close the card in TinyAgentDeck. Since you committed in step 1 — no changes left behind — the app deletes the worktree automatically.

The leftover tad/session-… branch was merged in step 2 and is no longer needed. Choose "Delete branch too" in the "Orphan worktrees" section of the project dashboard, or remove it by hand.

git branch -d tad/session-…   # Delete the merged branch

Don't commit secrets

Files containing .env.local, API keys, or secrets must never be committed. If they're in .gitignore, they won't show up in git status (if one does show up, don't git add it).

Environment variables you wrote only on the worktree side don't exist in the main folder. Only when you want to test locally, add the same values to the .env.local on the main side too. Production secrets are managed separately as environment variables on Cloudflare and the like, so this work doesn't affect them.

When you want to discard without committing

In the rare case of "it's already live in production, and I need neither the code nor the history," you can close the card without committing and choose force delete in the confirmation dialog — production keeps running. But since nothing remains in git at all, this is generally not recommended.

Cleaning up orphan worktrees

Worktrees created outside the app, or left behind for some reason, are listed as "orphan worktrees" in the project dashboard. You can delete them there, and turning on "Delete branch too" removes the branch after the worktree is gone (an irreversible action, so it asks for confirmation).

FAQ

Is it OK to have Claude do the commit and the merge into main too?

Yes — it's the easiest way. Paste the ask above into the worktree session's terminal. Claude figures it out, including leaving out secrets, and reports the result. If you already leave git to Claude, nothing changes.

If I delete the worktree, does the branch go too?

No. Deleting the worktree and deleting the branch are separate. If it's merged, git branch -d <name>; to force-delete an unmerged one, git branch -D <name>.

I forgot to merge into main and cleaned up.

As long as you committed, the branch is still there, so you can pull it in any time with git merge tad/session-…. The branch name is derived from the worktree's folder name (the session ID) as tad/session-<session-id>.

I don't know the branch name.

Check with git branch --show-current in the worktree's terminal, or git worktree list / git branch --list 'tad/session-*' in the repository.

Get TinyAgentDeck

Worktree isolation is built in. Run sessions in parallel, and just fold them away when you're done.

Download the free trial