Skip to Content
DocumentationGetting Started

Getting Started

worktree streamlines common Git worktree tasks into a repeatable workflow.

Install

Install globally:

npm install -g @northguild/worktree

Or run directly without global install:

npx @northguild/worktree —help

Agent skill

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

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

Run once inside your repository:

worktree config

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. Set it to none to open nothing: branch prints Worktree created at <path> and stops.

First Workflow

Create your first branch worktree:

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.

Requirements

  • Git available on your PATH
  • Node.js installed
  • 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

Last updated on
Commands