Worktrees

Run tasks on multiple branches in parallel without touching your main checkout. Untether creates isolated git worktrees so you can kick off work on @feat/auth and @fix/memory-leak at the same time — all from Telegram.

Configure worktree-based runs for a project#

Every registered project can run @branch tasks out of the box: worktrees_dir defaults to .worktrees inside the project. An existing local branch is checked out as is, a branch that only exists on origin is tracked from there, and a new branch is cut from worktree_base (default: the repo’s default branch, from origin/HEAD or the current branch). Set these keys only to change the location or the base branch:

untether config

untether config set projects.happy-gadgets.path "~/dev/happy-gadgets"
untether config set projects.happy-gadgets.worktrees_dir ".worktrees"
untether config set projects.happy-gadgets.worktree_base "master"

toml

[projects.happy-gadgets]
path = "~/dev/happy-gadgets"
worktrees_dir = ".worktrees"      # relative to project path
worktree_base = "master"          # base branch for new worktrees

Run in a branch worktree#

Send a message like:

/happy-gadgets @feat/memory-box freeze artifacts forever

Untether

working · codex · 5s · step 2

✓ Read src/memory.py
… Edit src/memory.py

dir: happy-gadgets @feat/memory-box

If the main checkout is already on the branch you name, the run uses the project directory itself and no worktree is created.

Ignore .worktrees/ in git status#

If you use the default .worktrees/ directory inside the repo, add it to a gitignore. One option is a global ignore:

git config --global core.excludesfile ~/.config/git/ignore
echo ".worktrees/" >> ~/.config/git/ignore

Context persistence#

When project/worktree context is active, Untether includes a dir: footer in messages. When you reply, this context carries forward (you usually don’t need to repeat /<project-alias> @branch).

Related#

• Context resolution