Skip to content
NorthGuildworktreev3.0.0

Getting Started with @northguild/worktree

worktree streamlines common Git worktree tasks into a repeatable workflow.

Install

Section titled “Install”

Install globally:

Terminal window
npm install -g @northguild/worktree

Or run directly without global install:

Terminal window
npx @northguild/worktree --help

Agent skill

Section titled “Agent skill”

To teach a coding agent how to drive worktree, including its --json agent mode, add the usage skill:

Terminal window
npx skills add northguild/worktree --skill worktree

At a terminal the command asks which agent(s) to install the skill into; run from inside a coding agent it installs without asking, and --agent <name> chooses. It installs into the current project; add --global (-g) to install it for your user instead, so the agent has it in every repository. It is separate from, and in addition to, the install above: the skill teaches an agent the CLI, it does not install the CLI.

Initial Configuration

Section titled “Initial Configuration”

Run once inside your repository:

Terminal window
worktree config

If your repository commits a .worktree.yml, worktree branch already has the team’s source branch, prefixes and Jira host and does not offer to configure them. The wizard says which keys the file sets and does not ask for them, so it no longer writes a personal copy of a team value; to override one for yourself, run worktree config <key> <value>. If the repository has no file yet, worktree config --project writes one from the team settings in your git config, and on a terminal worktree offers it once. See Project Configuration.

Common values:

  • defaultSourceBranch: usually origin/main
  • codeEditor: usually code
  • agent.command: optional, such as claude --bg, the command --agent runs to hand a brief to a coding agent

To open worktrees as Herdr spaces instead of editor windows, set opener to herdr — see Herdr Spaces. To open them as Rex sessions, set it to rex — see Rex Sessions. Set it to auto to open in whichever of the two the command runs inside, falling back to the editor. Set it to none to open nothing: branch prints Worktree created at <path> and stops.

First Workflow

Section titled “First Workflow”

Create your first branch worktree:

Terminal window
worktree branch feature/improve-readme

This command will:

  1. Branch from your configured source branch.
  2. Create a worktree under <repo>.worktrees/feature/improve-readme.
  3. Copy the gitignored env files from your main repository — .env*, .dev.vars* and .envrc.
  4. Open the new worktree in your configured editor, or as a Herdr space when opener is herdr, or as a Rex session when it is rex; with auto, in the Herdr or Rex you are in, else the editor.

Requirements

Section titled “Requirements”
  • Git available on your PATH
  • Node.js ^22.13.0 or >=23.5.0 (the range @inquirer/prompts and @oclif/core 5 both support; Node 20 and 21 are not)
  • Existing Git repository
  • macOS or Linux — Windows is not supported

If you use automatic editor opening, ensure your editor command is available on your PATH (for example, code).

Next

Section titled “Next”