Automatic worktree initialization

Korus can prepare a newly created Git worktree before its agent starts working. This saves you from repeating dependency installation and local configuration setup for every parallel task.

Choose a mode under Settings → Git → Worktrees → Worktree initialization:

Mode	What Korus does
Auto-detect (default)	Runs a repository setup script if one is present. Otherwise, copies local environment files and installs dependencies for recognized projects.
Repo instructions only	Runs a repository setup script if one is present. Without one, leaves the new worktree as a plain Git checkout.
Disabled	Creates the Git worktree without running setup or copying environment files.

Initialization runs when Korus creates a new worktree, including worktree delegation. Attaching to or reusing an existing worktree does not run it again. Moving current work with the Branch action also skips initialization so setup cannot interfere with the changes being transferred.

Full automatic setup: Auto-detect

Use Auto-detect for projects that follow standard package-manager conventions.

Korus first checks for a repository setup script. If it finds one, that script takes full control of initialization, as described below. If there is no script, Korus:

1. Copies local environment files from another checkout of the repository, without overwriting files already in the new worktree.
2. Detects dependency setup from files at the new worktree's root.
3. Runs the detected commands in sequence: JavaScript/TypeScript, then Python, then Go. A repository using more than one ecosystem gets each applicable setup step.

This is package-based setup, not an agent inventing and running arbitrary bootstrap commands. Custom build steps, database setup and service startup belong in a repository script.

JavaScript and TypeScript

A root package.json enables Node package-manager detection. Its packageManager field takes priority. Otherwise, Korus checks lockfiles in this order: pnpm, Yarn, Bun, then npm.

Package manager	Command
pnpm	pnpm install --frozen-lockfile when pnpm-lock.yaml exists; otherwise pnpm install.
Yarn	With yarn.lock, uses yarn install --immutable if .yarnrc.yml exists, or yarn install --frozen-lockfile otherwise. Without a lockfile, uses yarn install.
Bun	bun install --frozen-lockfile when bun.lock or bun.lockb exists; otherwise bun install.
npm	npm ci when package-lock.json exists; otherwise npm install --package-lock=false.

For a workspace-based monorepo, the root package-manager command can install its workspaces. Korus does not independently search every subdirectory for projects to install.

Python

Korus uses the first matching root file:

File	Setup
uv.lock	uv sync
poetry.lock	poetry install
Pipfile.lock	pipenv sync
requirements.txt	Creates .venv, then installs the requirements using that environment's Python.

For requirements.txt, macOS/Linux use python3 -m venv .venv, followed by .venv/bin/python -m pip install -r requirements.txt. Windows uses py -3 -m venv .venv, followed by .venv\Scripts\python.exe -m pip install -r requirements.txt.

Go

A root go.mod triggers go mod download.

Local environment files

The automatic fallback copies .env and .env.* files, including files in project subdirectories. It prefers the checkout containing the repository's default branch. If that is unavailable, it uses the source repository folder, then another available checkout.

• Existing destination files are preserved.
• Template files ending in .dist, .example, .sample or .template are excluded.
• Dependency directories, virtual environments, build output and caches are skipped, including node_modules, .venv, dist, build, coverage, target and vendor.
• Nested Git checkouts and the newly created worktree itself are skipped.

For example, .env.local and apps/api/.env.test can be copied, while .env.example and an environment file inside node_modules are not. Copying a file does not add it to Git; keep local credentials excluded by your repository's ignore rules.

Environment copying belongs to the automatic fallback. Repo instructions only does not copy environment files, and neither mode copies them automatically when a repository setup script is selected.

Repository-controlled setup scripts

Use Repo instructions only when your team wants explicit, versioned setup. Scripts also work in Auto-detect, where they take precedence over automatic setup.

Put the script in the branch being checked out, under .agents/worktree/. Korus looks in the new worktree, so an uncommitted script that exists only in your original checkout is not enough.

Host operating system	Preferred script	Fallback
macOS	.agents/worktree/setup-macos.sh	.agents/worktree/setup
Linux	.agents/worktree/setup-linux.sh	.agents/worktree/setup
Windows	.agents/worktree/setup-win.ps1	.agents/worktree/setup

Only one script is selected: the operating-system-specific file wins over the generic setup file. Korus executes these files as scripts; they are not prose instructions for an agent to interpret.

A selected script owns all setup. Korus does not run inferred dependency commands or automatic environment copying before or after it. Include those steps in the script if the project needs them. An empty or whitespace-only script is an intentional no-op and also suppresses the automatic fallback.

Execution environment

Scripts run with the new worktree as their working directory. They inherit the host environment and receive:

Variable	Value
AGENT_WORKTREE_PATH	Absolute path of the new worktree.
AGENT_WORKTREE_SOURCE_PATH	Source repository path used to create it.
CI	The inherited value, or 1 if it was not set.

The source path is not necessarily the default-branch checkout. If a script copies local files, choose its source deliberately.

On macOS and Linux, Korus invokes the file with /bin/sh. Use POSIX shell syntax, or explicitly invoke another interpreter from your script. An executable bit is not required. On Windows, Korus runs PowerShell with -NoProfile -NonInteractive -ExecutionPolicy Bypass; a .ps1 file is passed with -File, while the generic setup file is interpreted as PowerShell command text. Use platform-specific scripts when the commands differ across operating systems.

Example: dependencies and a local environment file

For an npm project on macOS/Linux, create .agents/worktree/setup:

#!/bin/sh
set -eu

# Preserve an environment file already present in the new checkout.
if [ -f "$AGENT_WORKTREE_SOURCE_PATH/.env.local" ] && [ ! -e .env.local ]; then
  cp "$AGENT_WORKTREE_SOURCE_PATH/.env.local" .env.local
fi

npm ci

Commit the script to the branch new worktrees will start from. With Repo instructions only, every new worktree that contains it gets exactly these setup steps. With Auto-detect, the same script replaces the built-in fallback.

For more elaborate setup, the file can call a script you already maintain, such as sh scripts/bootstrap.sh. Keep setup noninteractive and make failures produce a nonzero exit code. set -eu in shell scripts helps ensure an early failure is not hidden by a later successful command.

Progress and troubleshooting

Korus shows setup progress while creating the worktree. Commands run sequentially; a failed command stops the sequence and reports an error. A repository script must return success before setup is considered complete.

If setup fails:

1. Check the reported command and error. Confirm the required package manager or interpreter is installed and available to Korus on the host creating the worktree.
2. Inspect the new folder and branch before retrying. Git creation may already have succeeded even though setup failed.
3. Fix the cause and finish setup in that worktree when appropriate. Reusing an existing worktree does not rerun initialization.

Initialization prepares files and dependencies; it does not guarantee that development servers, databases or other services are running. Use repository scripts when those require project-specific preparation, and use separate ports and resources for concurrent worktrees.

For the broader workflow, see Worktrees.