worktree config

Configure defaults and inspect current configuration.

Usage

worktree config
worktree config <key> <value>
worktree config <key>
worktree config --list
worktree config --list --missing
worktree config --missing
worktree config --missing --names <comma-separated-keys>
worktree config --yes --names <comma-separated-keys>

worktree config <key> with no value prints the current value and nothing else, secrets included as --list does, so token=$(worktree config github.token) works in a script. A key with no value prints nothing and exits 0.

--missing filters to values that are not configured yet.

• With --list, it only prints config names that currently have no value.
• Without --list, it only prompts for missing values.
• --names limits prompting to specific config keys. Naming keys is asking for them, so the optional group confirms (Jira, GitHub, prefixes, opener, editor, Herdr, agent) are not asked for them.
• --yes (-y) makes the run non-interactive: nothing is asked. Each key takes its default, or the value it already holds, and the run fails with exit 2 naming worktree config <key> <value> for a key with neither, such as a token. Without --names the optional groups have no default and the run fails naming --names <keys>.

Examples

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

Configuration is stored in local Git config under northguild.worktree.*.

Opener Keys

• opener selects where a finished worktree opens, and for herdr where its space is closed again when the worktree is removed: editor (default), herdr or none. With none nothing is opened: the command prints Worktree created at <path> and stops. An unknown value fails with exit 2.
• codeEditor the editor executable plus any arguments, used when opener is editor.
• herdr.focus whether a new Herdr space comes to the front. Defaults to true.
• herdr.agent the agent kind that starts in every newly opened Herdr space, with or without a brief. Unset means no agent, unless branch or checkout is given a brief (--agent), in which case the program agent.command names is used.

opener and codeEditor are always listed and prompted for. herdr.focus and herdr.agent are listed and prompted for only when the herdr CLI is on your PATH, or when one of them already has a value (or opener is herdr). --names and a direct worktree config <key> <value> always work regardless, so a machine can be configured before Herdr is installed.

GitHub Integration Keys

• github.token for GitHub API access.
• github.autoAssign whether reading a GitHub issue also assigns it to you: true always, false never, unset means you are asked once and your answer is saved. See Configuration.
• branchPrefix.feature optional prefix used for Feature issues.
• branchPrefix.bugfix optional prefix used for Bug issues.
• branchPrefix.chore optional prefix used for Task issues.

github.token and github.autoAssign are asked together behind one confirm, so declining costs a single yes/no. The github.autoAssign prompt has three choices: “Yes, always”, “No, never” and “Ask me each time”. The last leaves the key unset, clearing any stored answer, which is the “ask me” state — so --missing goes on offering the prompt until you settle it either way. Leaving the github.token prompt empty keeps any token you already have, rather than clearing it.

Agent Key

• agent.command the command --agent runs to hand a brief to a coding agent. It does not start an agent on its own: without a brief, only herdr.agent does. The wizard asks for it behind a yes/no, and the herdr.agent question is asked separately. Read by branch --agent and checkout --agent, by list --agents, and by cleanup’s agent check. See Configuration.

Post-create Key

• postCreate a command to run in every new worktree, such as pnpm install. Read by branch; when it is unset the command is inferred from the lockfile instead. It is validated like agent.command: its first word has to be on PATH. See Configuration. The prompt accepts an empty answer, which leaves it unset.