===============
LIBRARY RULES
===============
From library maintainers:
- Create a new branch in its own worktree with `worktree branch`; use `worktree checkout` only for a branch that already exists on the remote, because it fails for one that does not.
- Run `worktree` only inside a git repository, and run `worktree config` once per repository before first use.
- Give `--source` with the `origin/` prefix, such as `origin/main`, because a bare `main` prompts for confirmation and a non-interactive run exits 2 instead of waiting.
- Set `agent.command` (or `herdr.agent` when `opener` is `herdr`) before using `--agent`, because a brief with no agent configured to take it exits 2 before any worktree is created.
- In scripts, CI or another agent, pass explicit values such as `remove <branch> -f` and `cleanup --force`, because a non-interactive run never prompts and a value with no default fails at once with exit 2.
- Use `--json` on `branch`, `list` and `remove` to get one JSON document to parse, and when a brief matters check `agent.prompted` in the `branch` document, not just the exit code.

### Configure `agent.command` before using `--agent`

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Shows the incorrect and correct setup for using `--agent`. A brief with no agent configured to take it exits `2` before any worktree is created, naming the missing key: `worktree config agent.command "<command>"` for the detached start (editor or `none` opener, `--no-open`, or Herdr not installed), or `worktree config herdr.agent <kind>` on the Herdr path, where `herdr.agent` alone is enough (`branch` and `checkout` both). Set the key first, or check `worktree config --list`. The soft path remains only for a run where Herdr was the opener, had an agent kind, and did not open: with no `agent.command` to fall back to, the worktree is created, a `No agent configured` warning is printed, and the exit code is `1` because the brief was not delivered.

```bash
# Nothing set agent.command
worktree branch feature/x --agent "add bulk actions to the table"
```

```bash
worktree config agent.command "claude --bg"
worktree branch feature/x --agent "add bulk actions to the table"
```

--------------------------------

### Install worktree globally with bun

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Installs the @northguild/worktree package globally using bun.

```bash
bun add -g @northguild/worktree
```

--------------------------------

### Agent Dispatch Examples

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/branch/page.mdx

Examples of using the --agent flag with a direct string prompt or an external file path.

```bash
worktree branch feature/add-bulk-actions --agent "add bulk actions to the table"
worktree branch --github 42 --agent-file brief.md
```

--------------------------------

### worktree branch examples

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/branch/page.mdx

Concrete examples of `worktree branch` covering basic creation, source branching, GitHub/Jira issue integration, agent modes, and flags for open/install/JSON output.

```bash
worktree branch feature/add-bulk-actions
worktree branch feature/add-bulk-actions --source origin/release/1.4
worktree branch --github 42
worktree branch --github "#42"
worktree branch --github 42 --assign
worktree branch --github 42 --no-assign
worktree branch --jira DEV-123
worktree branch --jira dev-123
worktree branch feature/add-bulk-actions --agent "add bulk actions to the table"
worktree branch --github 42 --agent "implement the issue"
worktree branch --github 42 --agent-file brief.md
cat brief.md | worktree branch --github 42 --agent-stdin
worktree branch --github 42 --no-agent
worktree branch feature/add-bulk-actions --no-open
worktree branch feature/add-bulk-actions --install
worktree branch feature/add-bulk-actions --no-install
worktree branch --github 42 --json --agent-file brief.md
```

--------------------------------

### worktree config examples

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/config/page.mdx

Examples of setting and querying configuration values, including setting defaults, toggling options, and using `--list` and `--missing` to inspect configuration. The `--missing` option filters to unconfigured values, and `--names` limits prompting to specific keys.

```bash
worktree config defaultSourceBranch origin/main
worktree config codeEditor code
worktree config opener herdr
worktree config opener none
worktree config opener
worktree config agent.command "claude --bg"
worktree config postCreate "pnpm install"
worktree config github.autoAssign true
worktree config --list
worktree config --list --missing
worktree config --missing
worktree config --missing --names defaultSourceBranch
worktree config --missing --yes --names branchPrefix.feature,branchPrefix.bugfix,branchPrefix.chore
```

--------------------------------

### branch document from --json

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Example of the `branch` document printed by `--json` on stdout. A count that could not be taken is `null`, never `0`; tokens are never printed. `issue` is `{provider,number,url}` or `{provider,key,url}` or `null`; `assigned` is `null` when no assignment was attempted; `herdr` and `agent` are `null` when skipped; `installed` is `{ran:false,reason}` when skipped. A failed install or an undelivered brief still prints the whole document, sets `installed.ok` to `false` or `agent.prompted` to `false`, and exits `1`.

```json
{"path":"/abs/repo.worktrees/42-fix-login","branch":"42-fix-login","source":"origin/main",
 "issue":{"provider":"github","number":42,"url":"https://github.com/acme/demo/issues/42"},"assigned":true,
 "envFilesCopied":["docs/.env.local"],
 "installed":{"ran":true,"command":"pnpm install --frozen-lockfile","inferred":true,"ok":true},
 "herdr":{"space":"w5","pane":"w5:p1","agent":"wt-42-fix-login"},
 "agent":{"name":"demo-42-fix-login","kind":"claude","command":["claude","--name","demo-42-fix-login"],"prompted":true},
 "warnings":[]}
```

--------------------------------

### Install and configure @northguild/worktree

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Install the CLI globally, run `worktree config` once inside a git repository to set defaultSourceBranch, codeEditor, agent.command, and postCreate (each behind a confirm), then create a first worktree. The Herdr keys herdr.focus and herdr.agent are offered only when `herdr` is on PATH; opener is always offered. `worktree config <key>` prints one value for scripts.

```bash
npm install -g @northguild/worktree

# Run once inside your git repository
worktree config
# prompts for: defaultSourceBranch (e.g. origin/main), codeEditor (e.g. code)
# agent.command (e.g. claude --bg) and postCreate (e.g. pnpm install), each
# behind a confirm. The Herdr keys
# herdr.focus and herdr.agent are offered only when `herdr` is on PATH; opener is
# always offered. `worktree config <key>` prints one value, for scripts.

# Create your first worktree
worktree branch feature/my-feature
```

--------------------------------

### worktree checkout examples

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/checkout/page.mdx

Example invocations of checkout. The first two check out a local or remote branch; the third passes an agent prompt. Each creates a local tracking branch and a worktree directory for that branch.

```bash
worktree checkout feature/fix-login-timeout
worktree checkout origin/feature/fix-login-timeout
worktree checkout feature/fix-login-timeout --agent "find the cause of the timeout"
```

--------------------------------

### Install worktree globally with yarn

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Installs the @northguild/worktree package globally using yarn.

```bash
yarn global add @northguild/worktree
```

--------------------------------

### Install worktree globally with pnpm

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Installs the @northguild/worktree package globally using pnpm.

```bash
pnpm add -g @northguild/worktree
```

--------------------------------

### worktree list --agents example output

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/list/page.mdx

Example output of worktree list --agents, showing the agent session markers: [waiting], [done], [interactive], and [interactive, waiting]. A worktree with no Agent: detail has no session in it.

```text
- feature/one (Agent: feature-one-1f)
- feature/two (Ahead: 2, Behind: 1, Agent: feature-two-1f [waiting])
- feature/three (Agent: notes-1f [interactive])
- feature/four (Agent: feature-four-1f [interactive, waiting])
- feature/five (Agent: feature-five-1f [done])
```

--------------------------------

### Install worktree globally with npm

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Installs the @northguild/worktree package globally using npm.

```bash
npm install -g @northguild/worktree
```

--------------------------------

### JSON output: example response

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/remove/page.mdx

Example JSON output showing removed worktrees, closed Herdr spaces, and warnings.

```json
{"removed":[{"branch":"feature/add-bulk-actions","path":"/abs/repo.worktrees/feature/add-bulk-actions"}],"herdrSpacesClosed":["w5"],"warnings":[]}
```

--------------------------------

### Hand a new worktree to a coding agent

Source: https://github.com/northguild/worktree/blob/main/README.md

Creates a new worktree and hands it to a coding agent. The agent starts with the new worktree as its working directory and the flag's value as its prompt. There is one agent per worktree; with opener set to herdr, Herdr starts it in the new space and the prompt is submitted afterwards. A brief with no agent to take it exits 2 before creating anything.

```bash
worktree branch feature/add-bulk-actions --agent "add bulk actions to the table"
```

--------------------------------

### Output: Copying env files

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/env-files/page.mdx

Example output from the worktree command listing copied env files. Shows the heading and each copied file path with a checkmark. The output is sent to standard output, so it can be piped or redirected.

```text
Copying 4 env files from /Users/you/code/acme:
  ✔ .env
  ✔ .env.local
  ✔ docs/worker/.dev.vars
  ✔ tmp/backup/.env.old
```

--------------------------------

### Suggested setup: configure Jira and branch prefixes

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/jira-integration/page.mdx

Configure Jira host, email, API token, and branch prefixes for feature, bugfix, and chore issue types. These settings are stored in local git config.

```bash
worktree config jira.host https://your-domain.atlassian.net
worktree config jira.email your-email@example.com
worktree config jira.apiToken <api-token>
worktree config branchPrefix.feature feature/
worktree config branchPrefix.bugfix fix/
worktree config branchPrefix.chore chore/
```

--------------------------------

### worktree open example with branch

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/open/page.mdx

Opens the worktree for the branch feature/add-bulk-actions. If the branch is omitted, an interactive picker is shown; in non-interactive runs without the argument, the command exits with code 2 and prints an error message.

```bash
worktree open feature/add-bulk-actions
```

--------------------------------

### Confirmation prompt: ahead by commits

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/remove/page.mdx

Example of the confirmation prompt shown when the branch is ahead by commits.

```text
This branch is 1 commit ahead so you might lose some work. Are you sure you want to remove this worktree?
```

--------------------------------

### Examples: worktree remove and rm alias

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/remove/page.mdx

Demonstrates removing a worktree with and without `--force`, and shows the `rm` alias.

```bash
worktree remove feature/add-bulk-actions
worktree remove feature/add-bulk-actions --force
worktree rm feature/add-bulk-actions
```

--------------------------------

### cleanup skipped worktrees output

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/cleanup/page.mdx

Example output showing the three categories of worktrees that are skipped: those with uncommitted changes, those whose unpushed commits could not be counted, and those with a live agent session.

```text
Skipped 1 worktree branch that has uncommitted changes:
- feature/wip (Remote removed, 3 uncommitted changes)
Skipped 1 worktree branch whose unpushed commits could not be counted:
- feature/orphan (Unpushed commits unknown: no comparison base; set defaultSourceBranch or run git remote set-head origin --auto)
Skipped 1 worktree branch with a live agent session:
- feature/api (Remote removed, Agent: feature-api-1f)
```

--------------------------------

### Configure GitHub integration settings

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/github-issue-integration/page.mdx

Suggested setup for GitHub integration. Configures the GitHub token, auto-assign behavior, and branch prefixes for issue types. The token is required for assigning issues and must have push access to the repository.

```bash
worktree config github.token <token>
worktree config github.autoAssign true
worktree config branchPrefix.feature feature/
worktree config branchPrefix.bugfix fix/
worktree config branchPrefix.chore chore/
```

--------------------------------

### Configure Herdr opener with worktree config

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/herdr-spaces/page.mdx

Configure the opener to use Herdr, either by setting it explicitly or by prompting for it. The first command works even if Herdr is not yet installed; the second prompts for the opener regardless.

```bash
worktree config opener herdr                      # works whether or not herdr is installed yet
worktree config --missing --names opener          # prompts for it regardless
```

--------------------------------

### worktree branch and checkout with agent options

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Shows how to create a worktree branch with an agent brief, using --agent, --agent-file, --no-agent, --no-open, and checkout with -a. The agent starts in the new worktree directory. The brief is passed as a single argument, so quotes and spaces are safe.

```bash
# Detached (non-Herdr) runs need agent.command, e.g. claude --bg; with opener herdr, herdr.agent alone is enough
worktree branch feature/add-bulk-actions --agent "add bulk actions to the table"
worktree branch --github 42 --agent-file brief.md   # or --agent-stdin; exclusive, max 131,071 bytes
worktree branch feature/x --no-agent                # open, but start no agent
worktree branch feature/x --no-open                 # print the path, open nothing
worktree checkout feature/fix-login-timeout -a "find the cause of the timeout"
```

--------------------------------

### worktree branch --json output for GitHub issue

Source: https://github.com/northguild/worktree/blob/main/README.md

Shows the JSON output of `worktree branch --json` for a GitHub issue. The output is a single line with one document; a count that could not be taken is `null`, never `0`, and tokens are never printed. The `issue` field is `{provider:"github",number,url}`, `{provider:"jira",key,url}`, or `null`; `assigned` is `null` when no assignment was attempted; `herdr` and `agent` are `null` when skipped; `agent.command` leaves the brief out; `agent.name` is `null` for a detached start. `installed` is `{ran:false,reason}` when skipped, and a failed install still prints the whole document with `installed.ok` `false` and exits `1`.

```bash
worktree branch --github 42 --json --agent-file brief.md
```

```json
{"path":"/abs/repo.worktrees/42-fix-login","branch":"42-fix-login","source":"origin/main",
 "issue":{"provider":"github","number":42,"url":"https://github.com/acme/demo/issues/42"},"assigned":true,
 "envFilesCopied":["docs/.env.local"],
 "installed":{"ran":true,"command":"pnpm install --frozen-lockfile","inferred":true,"ok":true},
 "herdr":{"space":"w5","pane":"w5:p1","agent":"wt-42-fix-login"},
 "agent":{"name":"demo-42-fix-login","kind":"claude","command":["claude","--name","demo-42-fix-login"],"prompted":true},
 "warnings":[]}
```

--------------------------------

### Show worktree CLI help

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/faq/page.mdx

Display help for the worktree CLI and for a specific command. Use these to see all command options.

```bash
worktree --help
worktree <command> --help
```

--------------------------------

### Add worktree agent skill

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Adds the worktree usage skill to a coding agent. At a terminal it asks which agent(s) to install into; run from inside a coding agent it installs without asking. Use --agent <name> to choose, and --global (-g) to install for your user instead of the current project.

```bash
npx skills add northguild/worktree --skill worktree
```

--------------------------------

### Configure agent kind for worktree spaces

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/herdr-spaces/page.mdx

Sets the herdr.agent configuration to claude, enabling the agent to start when a space is opened. The value is the agent kind Herdr should start, such as claude, codex, or gemini. This is optional and off unless set or a brief is provided.

```bash
worktree config herdr.agent claude
```

--------------------------------

### Configure all Jira keys before using `worktree branch --jira`

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Contrasts incomplete and complete Jira configuration for the `--jira` flag. All three Jira keys (`jira.host`, `jira.email`, `jira.apiToken`) are required; missing any one causes an authentication error when the CLI calls the Jira API.

```bash
worktree config jira.host https://company.atlassian.net
worktree branch --jira DEV-123
```

```bash
worktree config jira.host https://company.atlassian.net
worktree config jira.email your@company.com
worktree config jira.apiToken ATATT3xFfGF...
worktree branch --jira DEV-123
```

--------------------------------

### worktree config examples

Source: https://github.com/northguild/worktree/blob/main/README.md

Sets configuration values under the northguild.worktree.* namespace. codeEditor runs without a shell, so quotes group but ~ and $VAR are not expanded. Set opener to none to open nothing, or to herdr to open worktrees as Herdr spaces. Use --list to show stored values and --missing to show unset keys.

```bash
worktree config defaultSourceBranch origin/main
worktree config codeEditor code
worktree config opener herdr
worktree config agent.command "claude --bg"
worktree config --list
worktree config --missing
```

--------------------------------

### Confirmation prompt: uncommitted changes

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/commands/remove/page.mdx

Example of the confirmation prompt shown when the branch has uncommitted changes.

```text
This branch has 3 uncommitted changes so you might lose some work. Are you sure you want to remove this worktree?
```

--------------------------------

### Run `worktree config` before first use

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Shows the incorrect and correct sequences for first use of the worktree CLI. Without `defaultSourceBranch` set, `branch` offers to run `config` in a terminal and uses `origin/main` when non-interactive, with a warning naming the missing key. Without `codeEditor`, the worktree is created but not opened — unless `opener` is `herdr`, which ignores `codeEditor` and opens a Herdr space instead, or `none`, which opens nothing.

```bash
npm install -g @northguild/worktree
worktree branch feature/x
```

```bash
npm install -g @northguild/worktree
worktree config          # run once per repo
worktree branch feature/x
```

--------------------------------

### Configure worktree keys with `worktree config`

Source: https://github.com/northguild/worktree/blob/main/skills/worktree/SKILL.md

Shows common invocations of `worktree config` for managing configuration keys stored under `northguild.worktree.*`. Use `--missing` to configure only unset keys, optionally restricting to specific names with `--names`. `--yes` runs non-interactively, taking each key's default or failing while naming the key (e.g., `worktree config github.token <token>`). `--list` prints all current values.

```bash
# Configure only missing keys
worktree config --missing

# Configure specific keys
worktree config --missing --names jira.host,jira.email,jira.apiToken

# Non-interactive: takes each key's default, or fails naming the key
# (for example `worktree config github.token <token>`)
worktree config --yes --names branchPrefix.feature,branchPrefix.bugfix

# List all current values
worktree config --list
```

--------------------------------

### Run worktree directly with bunx

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Runs the worktree CLI without global installation using bunx.

```bash
bunx @northguild/worktree --help
```

--------------------------------

### Configure editor and open worktree

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/guides/editor-integration/page.mdx

Configure the editor command once with `worktree config codeEditor code`, then open a worktree with `worktree open feature/add-bulk-actions`. If the editor is not configured, `worktree open` shows an interactive branch picker; similarly, `worktree checkout` shows an interactive remote branch picker when the editor is omitted.

```bash
worktree config codeEditor code
```

```bash
worktree open feature/add-bulk-actions
```

--------------------------------

### Run worktree directly with npx

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Runs the worktree CLI without global installation using npx.

```bash
npx @northguild/worktree --help
```

--------------------------------

### Create a branch worktree

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Creates a new branch worktree. It branches from the configured source branch, creates a worktree under <repo>.worktrees/feature/improve-readme, copies gitignored env files (.env*, .dev.vars*, .envrc), and opens the worktree in the configured editor or Herdr space.

```bash
worktree branch feature/improve-readme
```

--------------------------------

### Run worktree directly with yarn dlx

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Runs the worktree CLI without global installation using yarn dlx.

```bash
yarn dlx @northguild/worktree --help
```

--------------------------------

### Run worktree config

Source: https://github.com/northguild/worktree/blob/main/docs/src/app/docs/getting-started/page.mdx

Runs the initial configuration command inside your repository. Common values include defaultSourceBranch (usually origin/main), codeEditor (usually code), and agent.command (optional, such as claude --bg).

```bash
worktree config
```