.vibe.toml

The .vibe.toml file contains shared configuration that is typically committed to git and shared with your team.

Copy Configuration

Files

Copy individual files from the origin repository to the worktree:

[copy]
files = [".env", "config.json"]

Glob Patterns

The files array supports glob patterns for flexible file selection:

[copy]
files = [
  "*.env",              # All .env files in root
  "**/*.json",          # All JSON files recursively
  "config/*.txt",       # All .txt files in config/
  ".env.production"     # Exact paths still work
]

Supported patterns:

Pattern	Description
`*`	Matches any characters except `/`
`**`	Matches any characters including `/` (recursive)
`?`	Matches any single character
`[abc]`	Matches any character in brackets

Directories v0.4.0+

Copy entire directories recursively:

[copy]
dirs = [
  "node_modules",      # Exact directory path
  ".cache",            # Hidden directories
  "packages/*"         # Glob pattern for multiple directories
]

Concurrency v0.17.0+

Control the number of parallel directory copy operations:

[copy]
concurrency = 8

Default: 4
Range: 1 to 32
Higher values may speed up copying on systems with fast storage (NVMe, SSDs)
Lower values reduce system resource usage

Environment variable override:

VIBE_COPY_CONCURRENCY=16 vibe start feat/my-feature

The environment variable takes precedence over the config file setting.

Copy Performance Optimization v0.4.0+

vibe automatically selects the best copy strategy based on your system:

Strategy	When Used	Platform
Clone (CoW)	Directory copy on APFS	macOS
Clone (reflink)	Directory copy on Btrfs/XFS	Linux
rsync	Directory copy when clone unavailable	macOS/Linux
robocopy (`/MT`)	Directory copy	Windows
Standard	File copy, or fallback	All

How it works:

File copy: Always uses native copyFile() for best single-file performance
Directory copy: Automatically uses the fastest available method

Benefits:

Copy-on-Write is extremely fast as it only copies metadata, not actual data
No configuration needed - the best strategy is auto-detected
Automatic fallback ensures copying always works

Hooks Configuration

See Hooks for details on configuring pre/post hooks.

Submodules Configuration

Load trusted .vibe.toml files from selected direct submodules after the worktree is created and before the parent repository’s pre_start hooks run:

[submodules]
configs = ["libs/foo", "vendor/bar"]

Default: []
Each entry must exactly match a direct submodule path in .gitmodules
Runs git submodule update --init -- <paths> in the new worktree
Loads each submodule’s .vibe.toml / .vibe.local.toml with that submodule’s own trust entry
Runs the submodule config’s hooks and copy rules with paths resolved from the submodule root
--no-hooks skips submodule hooks, but does not skip submodule initialization
--no-copy skips submodule copy rules
Submodule update, trust, path validation, or setup failures abort vibe start and leave the created worktree available for inspection

Worktree Configuration v0.6.0+

Customize the worktree directory path using an external script.

path_script

Specify a script that outputs the worktree path:

[worktree]
path_script = "~/.config/vibe/worktree-path.sh"

The script receives these environment variables:

Variable	Description	Example
`VIBE_REPO_NAME`	Repository name	`my-project`
`VIBE_BRANCH_NAME`	Branch name	`feat/new-feature`
`VIBE_SANITIZED_BRANCH`	Sanitized branch name (`/` → `-`)	`feat-new-feature`
`VIBE_REPO_ROOT`	Repository root path	`/path/to/repo`

Example script:

#!/bin/bash
echo "${HOME}/worktrees/${VIBE_REPO_NAME}-${VIBE_SANITIZED_BRANCH}"

Full Example

[copy]
files = [
  ".env",
  ".env.local",
  "**/*.secret"
]
dirs = [
  "node_modules",
  ".cache",
  "vendor"
]
concurrency = 8

[hooks]
pre_start = ["echo 'Preparing worktree...'"]
post_start = [
  "pnpm install",
  "pnpm db:migrate",
  "pnpm build"
]
pre_clean = ["git stash"]
post_clean = ["echo 'Cleanup complete'"]

[submodules]
configs = ["libs/foo"]

[worktree]
path_script = "~/.config/vibe/worktree-path.sh"