#Fresh Worktrees

A Paseo plugin that fast-forwards the source checkout's clean local base branch before creating a branch-off workspace.

The plugin runs the refresh inside the Paseo daemon and adds a workspace-header indicator when an active worktree falls behind the source checkout's remote base.

#Demo

https://github.com/user-attachments/assets/d0687b37-8292-459d-ad28-7960c193195a

#Screenshots

The repository, remote, branch, and workspace are disposable local fixtures. Both PNGs come from an isolated Paseo test daemon at 2× pixel density. Browser DevTools rewrites local paths and host labels and verifies that no private organization names remain before capture.

#Behind indicator

#Installed plugin

#Behavior

Before Paseo creates a branch-off worktree, the plugin:

1. Resolves the source repository from the request path or Paseo project.
2. Fetches and prunes the relevant Git remote without interactive prompts.
3. For an implicit or local base such as main, verifies that branch is checked out and the source checkout is clean, then fast-forwards it to its remote-tracking branch.
4. Leaves the workspace request unchanged, so Paseo forks from the local branch.
5. Rechecks active worktrees every five minutes and shows Behind · N in the workspace header when their HEAD is behind the source branch's remote-tracking ref. Select the indicator to recheck it.

Explicit checkout and change-request workspaces are unchanged. Explicit remote bases are fetched but do not mutate a local branch. Repositories without remotes are unchanged. A dirty source checkout emits a warning and skips the local branch update, allowing workspace creation to continue from the existing local base. Failed fetches and non-fast-forward updates do the same. Concurrent requests for the same target share one refresh, and updates are serialized per repository.

#Sidebar footer (Paseo 0.11+)

On Paseo 0.11 and later a "Behind source branch" footer row shows how many workspaces are behind their source branch. Its popover lists them and offers Refresh all, which fast-forwards each clean source checkout to its upstream (never a dirty or diverged one, which are skipped and reported), then rechecks every listed workspace. Worktree branches are not touched. "Behind" compares the workspace HEAD with the remote-tracking ref of the source checkout's current branch, which is not necessarily the workspace's recorded base. Paseo 0.9 and 0.10 hosts get no footer row.

#Install

Paseo plugins are trusted, unsandboxed code. Review the source before installing it on the daemon host.

paseo plugin install npm:@omercnet/paseo-fresh-worktrees

The plugin requires Paseo ^0.9.0 || ^0.10.0 || ^0.11.0.

#Develop

bun install
bun run typecheck
bun run test