> ## Documentation Index
> Fetch the complete documentation index at: https://goldengoose.zue.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Worktree Init

> Repo-local native worktree bootstrap script for team member adds.

Worktree init is a repo-local bootstrap step for `gg_team_manage(add)` when gg creates a brand-new native worktree.

## Script path

When this feature is in play, gg looks for exactly:

* `.agents/gg/worktree-init.sh`

The script is resolved from the **new worktree checkout** that gg just created for the spawned member.

## When gg runs it

gg runs worktree init only when all of these are true:

* the operation is `gg_team_manage(add)`
* `worktree_name` is set
* `use_existing_worktree` is omitted or `false`
* gg creates a new native worktree owner session

gg does not run worktree init when:

* `worktree_name` is omitted
* `use_existing_worktree=true` (existing worktree reuse path)
* the spawned session inherits the caller's managed worktree reference as a consumer (no new worktree is created)

## Execution contract

* gg executes `./.agents/gg/worktree-init.sh` synchronously.
* Process cwd is the new worktree root (the same cwd gg sets on the spawned session template for native-owner creation).
* Missing script is a no-op.
* If the script exists but fails to spawn or exits non-zero, add-member fails before session creation.
* On that failure path, gg performs best-effort rollback of the newly created native worktree branch/path for the in-flight add operation.

## Hooks vs worktree init

Worktree init is separate from Team Hooks:

* `pre_teammate_add` hooks run earlier, before native worktree creation, in the source session cwd.
* Worktree init runs later, after new native worktree creation, in the new worktree cwd.
* The Add Agent pre-hook checkbox (`run_pre_teammate_add_hooks`) controls only hooks and does not disable worktree init.

For Team Hooks contracts, see [Configure: Hooks Reference](/configure/hooks-reference).

## Branch-specific behavior

Because the script is resolved from the new worktree checkout, behavior is branch-specific:

* the branch checked out in the new worktree controls which `worktree-init.sh` content runs
* an untracked local script present only in a different checkout does not automatically appear in the new worktree

## Related pages

* [How It Works: gg Tools](/how-it-works/gg-tools)
* [How It Works: Team Management](/how-it-works/team-management)
* [How It Works: Hooks](/how-it-works/hooks)
* [Configure: Hooks Reference](/configure/hooks-reference)