Manage Git worktrees on your computer from your phone

A practical guide to add, switch, and clean up Git worktrees remotely — with a phone workflow for review, small edits, and safe commits.

Based on
CLI
0.2.17
Preview ref
a2c45c8

Git worktrees can look like an advanced feature for “serious” Git people.

Then the same situation comes up over and over:

  • you’re in the middle of one change
  • a small hotfix pops up
  • or you need to review another branch quickly
  • and you don’t want to stash/unstash your way through it

Worktrees turned out to be the cleanest answer.

The second realization was more practical:

if you can manage worktrees from your phone, you stop blocking on “I’ll do it later when I’m back at my desk.”

This guide is a calm, repeatable workflow for worktrees — with a phone-first control surface.

Quick definition: what a worktree is (in plain language)

A Git repository normally has one working directory (your checked-out files).

A worktree lets one repo have multiple working directories, so you can check out more than one branch at a time.

Git’s own docs describe it as managing “multiple working trees attached to the same repository”, letting you check out more than one branch at a time. (Source: https://git-scm.com/docs/git-worktree)

Practically:

  • the repo’s object database is shared
  • each worktree gets its own checked out files + index/HEAD state

That’s why worktrees feel much lighter than “clone the repo twice”.

Common approaches and their trade-offs

When a hotfix interrupts a bigger change, the usual options are:

  • stash: works, but it’s easy to forget what you stashed and why
  • commit a WIP: works, but it pollutes history and invites mistakes
  • clone again: works, but it’s slow and duplicates a lot

Worktrees let you keep the main branch clean and keep momentum.

A workflow that works

This workflow uses a remote UI over the computer that owns the repo for day-to-day Git control.

Happier is one option that supports that approach.

Each Happier session is attached to a folder on your computer, and on a phone the session gives that folder its own Files and Git tabs. So a worktree folder plus a session in it is all you need.

Git write actions (commit, pull, push, branch switch) are experimental and off by default. You turn them on under Settings → Features → Source control operations (see the Git docs). Reading status and diffs works without it.

Trade-off: your computer still has to be online.

If you’re new to Happier (what it is, and where to get it)

If you haven’t seen Happier before: it’s an open-source companion app (mobile/web/desktop) that lets you keep workflows on a computer you trust, then manage them from your phone.

Get set up:

The mental model that prevents mistakes

Before you touch worktrees from a phone, adopt two rules:

  1. One worktree = one intent. If the hotfix is unrelated, it deserves its own worktree.

  2. Small edits from phone; deep surgery from keyboard. Your phone is great for review, light changes, and pushing a narrow fix.

Step-by-step: manage worktrees from your phone

1) Open a session in the repo folder

Open a session that runs in the repo, or start a new one and pick the repo folder on your computer as its working directory.

2) Use the Git tab as your “safety surface”

Inside the session:

  • open the Git tab
  • start on the changed files

This gives you a clean way to:

  • review what’s dirty
  • commit intentionally
  • sync (Pull/Push)

If you see:

  • Operation requires a clean working tree.

…treat it as a guardrail.

3) Create a new worktree (hotfix)

There are two ways to think about creating a worktree:

  • “I want a new directory for a new branch”
  • “I want a new directory for an existing branch”

In raw Git, that’s essentially:

  • git worktree add <path> (new branch convenience)
  • or git worktree add <path> <branch> (existing branch)

(Source: https://git-scm.com/docs/git-worktree)

In Happier, the key is the outcome:

  • a second working directory you can start its own session in
  • without disturbing whatever was already checked out

4) Keep phone edits narrow

Once the worktree exists, the phone loop is:

  1. open the session that runs in the worktree
  2. use Files to search the exact file
  3. make the smallest edit
  4. Save
  5. switch to the Git tab and review the diff
  6. select exactly the files that belong in the fix (supported since 0.2.12) and commit a small change

5) Push the hotfix (and stop)

Once the hotfix is pushed, stop.

The value of worktrees is that the hotfix doesn’t expand into a second full project.

It stays narrow.

6) Clean up worktrees (so they don’t become clutter)

Worktrees are powerful, but they can accumulate.

A good rule:

  • if the branch is merged, remove the worktree
  • if it’s long-running, keep it but name it clearly

In raw Git, stale administrative files can be cleaned up with git worktree prune if a worktree was deleted incorrectly. (Source: https://git-scm.com/docs/git-worktree)

In a UI-first workflow, the goal is simpler: don’t leave a pile of abandoned working directories.

Worktrees + multiple agents (why this started to matter)

Worktrees have been around for a while, but they become much more useful once you run more than one agent or session in parallel.

If you’re using Claude Code, Codex, or OpenCode, the basic multi-agent pattern looks like this:

  • one worktree per task
  • one session per worktree

That gives you isolation:

  • agents don’t step on each other’s files
  • diffs stay easier to review
  • commits stay narrower

In Happier, you can do this without turning your phone into a terminal:

  • create a worktree
  • launch a new session in that worktree folder (Claude/Codex/OpenCode)
  • monitor sessions from the same app where you also review diffs, commits, and history

This is intentionally not about “run 10 agents at once.”

It’s: run 2–3 in parallel, and keep them isolated so review stays sane.

Terminal (optional)

Sessions can show a Terminal tab when the embedded terminal is available. It’s experimental per the feature matrix and needs a connected daemon and a reachable machine.

Treat the terminal as the escape hatch for:

  • the one command the UI doesn’t expose
  • sanity checks
  • worktree cleanup when something is in a strange state

If you find yourself doing everything in terminal, it’s a signal to either:

  • simplify the workflow, or
  • wait for a keyboard

FAQ (real worktree questions)

What’s the difference between a branch and a worktree?

A branch is a pointer (a name for a line of commits).

A worktree is a separate working directory where you can check out a branch.

You typically use both together: one branch per worktree.

Why use worktrees instead of stashing?

Stashing is great for quick context switches.

Worktrees are great when the interruption is real work (a hotfix, a review, a test run) and you want zero chance of stepping on your current changes.

Can I have the same branch checked out in two worktrees?

By default, Git prevents checking out the same branch in two worktrees at once.

That’s a safety feature.

(You can do detached HEAD worktrees for “just run tests” style work without a branch.)

How do I name worktrees so future-me understands them?

Use names that encode intent:

  • hotfix-<ticket>
  • review-<pr>
  • release-<version>

What’s the biggest way worktrees go wrong?

Not the Git part.

The human part:

  • forgetting which worktree is “the one with unpushed changes”
  • leaving half-finished hotfix worktrees around

The fix is simple: keep worktrees narrow and clean them up.

When should I not use worktrees from my phone?

If you’re about to:

  • resolve conflicts
  • rebase interactively
  • do large refactors

Those are still best done at a keyboard.

What does “worktree is locked” mean?

Git lets you lock a worktree so it won’t be pruned/cleaned up automatically.

This is useful if the worktree lives on a disk or location that isn’t always mounted.

What does “prune” do, and when do I need it?

If a worktree folder is deleted incorrectly (not via git worktree remove), Git can end up with stale metadata.

git worktree prune cleans up those stale administrative files.

If you never delete worktree folders manually, you’ll rarely need this.

Can I use worktrees to keep long-running branches separate (not just hotfixes)?

Yes — that’s a great use.

Examples:

  • keep main clean in the primary worktree
  • keep release/<version> in a dedicated worktree
  • keep a long-running refactor in its own worktree

It reduces context switching and makes it easier to do quick reviews.

Do worktrees share node_modules / build artifacts?

Not automatically.

Each worktree is a separate directory, so most tooling treats it as a separate project folder.

If you want shared caches, that’s usually handled by the language/tooling layer (pnpm store, Gradle cache, etc.), not Git.

Where should I put worktree folders?

Put them next to the main repo folder, with clear names.

For example:

  • repo/ (main worktree)
  • repo--hotfix-123/
  • repo--release-1.2/

The best naming scheme is the one that makes it obvious, from a phone screen, what you’re looking at.

Can I remove a worktree safely from my phone?

Yes, but follow one safety rule first:

  • make sure it has no uncommitted changes
  • and no unpushed commits you still care about

A quick “Changed files” review before removal is cheap insurance.

Is git worktree the same thing as git switch / git checkout?

No.

  • switch/checkout changes what branch a single working directory points at.
  • worktree add creates a second working directory so you don’t have to switch away.

Should I use worktrees instead of branches?

No — worktrees complement branches.

A good default is still:

  • one branch per worktree

Can I use worktrees with submodules?

Yes, but be careful: each worktree has its own checkout state.

If submodules are part of your workflow, keep phone changes narrow and do the deeper “submodule surgery” at a keyboard.

gitworktreesmobileworkflows
Last updated: 2026-10-26