Init Scripts

Prepare a new worktree

A new worktree starts empty. No .envrc, no dependencies, no language server cache. An init script prepares it before the agent spawns.

What runs and when

Skip it for one create

• enabled is the config switch for every workspace. grove create --no-init turns it off for one workspace with no config edit, recording SKIPPED like enabled: false. The web dashboard's create dialog has no equivalent toggle today; use the CLI or edit the cascade for a one-off skip there.
• A root workspace runs in your real repo root, where a fresh-worktree script can do the wrong thing, so picking Root checks the box for you.
• The choice is never stored or re-applied on resume or respawn.

Fields

Scoping to host or container

A container workspace has its own setup step already: the devcontainer's postCreateCommand and lifecycle hooks. Grove's init script runs earlier, preparing the host worktree, the directory bind mounted into the container. Both run, so overlapping scripts prepare one environment twice. applies_to draws the line:

{
  "init_script": {
    "enabled": true,
    "inline": "cp .env.example .env",
    "applies_to": "host"
  }
}

The scope matches what the workspace actually is, not what was requested: a workspace that asked for a container and fell back to the host counts as host, so applies_to: "host" still runs for it. An excluded workspace fails nothing. Init reports SKIPPED.

What the script knows about its workspace

Grove exports four variables on every verb that runs the script: create, plus resume and respawn under run_on_resume.

They are derived from the workspace record on each run, so a branch rename leaves them correct instead of stale from create.

{
  "init_script": {
    "enabled": true,
    "inline": "echo \"setting up $GROVE_BRANCH in $GROVE_WORKTREE\""
  }
}

Inline and path are mutually exclusive

• Setting both in one layer fails at config load, before anything runs.
• Across the cascade, whichever layer sets inline or path last wins the whole choice, not just the field it touched. Grove drops the other field instead of merging both, logging a warning when that strips something.
• So a committed .grove/config.json path can serve as the team default while .grove/config.local.json swaps in an inline snippet, or the reverse.

Three patterns

Python project (uv)

{
  "init_script": {
    "enabled": true,
    "inline": "uv sync && cp ../.envrc .envrc",
    "timeout_seconds": 180
  }
}

Node project (pnpm)

{
  "init_script": {
    "enabled": true,
    "inline": "pnpm install --frozen-lockfile && pnpm prebuild",
    "timeout_seconds": 600
  }
}

Repo with a checked-in script

{
  "init_script": {
    "enabled": true,
    "path": "scripts/grove-init.sh",
    "timeout_seconds": 300
  }
}

The path is repo-relative. Grove invokes the configured shell, not the file's shebang.

Failure semantics

Init succeeds, fails, or is skipped. Grove records the outcome once for both create and resume, so the two paths cannot disagree, and the outcome rides the workspace record so the TUI and the dashboard read it without re-running the script. The display reads one of:

See also

• Daily workflow: where init fits in create and resume.
• Workspace lifecycle: what rollback does.
• Configuration cascade: how layers merge.
• Container workspaces: the lifecycle hooks that run alongside init.