Getting started

Install

Workler needs Node.js >= 18 and git on your PATH.

npm install -g workler
workler help

Create a workspace

Run add from any Git repository. There is no initialization step and no required configuration file.

workler add feature-a

Workler excludes .worktrees/ locally, clones the project into .worktrees/feature-a, and creates and checks out a new branch named feature-a:

cloning /path/to/project
     to /path/to/project/.worktrees/feature-a
create branch feature-a from HEAD
no workspace rules
done   feature-a
path   /path/to/project/.worktrees/feature-a

The workspace is a full, independent clone with its own HEAD, index, local branches, and fetch state.

Not sure what a command will do? Preview the full plan without changing anything:

workler add feature-b --dry-run

Optional copy and link rules

Create .workler only when a fresh workspace needs local files that Git does not carry:

link node_modules   # symlink back to the main project
copy .env           # copy into the workspace

• link <path> is useful for large, regenerable directories such as node_modules.
• copy <path> is useful for local configuration that each workspace may change independently, such as .env.

Rules are applied automatically by workler add. If you add or change them later, refresh an existing workspace with:

workler apply feature-a

When a workspace also needs a command to become usable — installing dependencies when there was no node_modules to link to, generating code — add a setup line. It runs in the new workspace once the rules are in place, and workler setup feature-a re-runs it later. With --if-missing <path> the command only runs while that path is absent, so the install below is skipped whenever the link rule put a node_modules in place:

setup --if-missing node_modules pnpm install

workler init is an optional convenience that creates a commented starter .workler, prepares .worktrees/, and records the local Git settings. You do not need it before using any command in a Git repository.

See Copy & link rules and Setup commands for the complete syntax and safety behavior.

Move around

workler list                        # every workspace, its branch, its path
cd "$(workler path feature-a)"     # enter a workspace

Or load the shell helper once and use wcd:

eval "$(workler shell-init)"    # put this in your shell rc
wcd feature-a
wcd main

Everyday commands

Command	What it does
workler add <name>	Clone a new workspace on a new branch, apply optional rules, run setup commands
workler apply <name>	Re-apply the rules to a workspace
workler setup <name>	Re-run the setup commands in a workspace
workler list	Show every workspace with its branch and path
workler path <name>	Print a workspace's path
workler remove <name>	Delete a workspace (refuses if it has local data: changes, untracked or ignored files)
workler status	Show branch, ahead/behind, and clean/dirty state
workler sync	Fetch everywhere and fast-forward what is safe

See the CLI reference for every command and flag.

Where to go next

• Workspaces & branches — bases, --branch, --checkout, and detached checkouts.
• Copy & link rules — the optional .workler format.
• Setup commands — setup --if-missing node_modules pnpm install and friends, run once a workspace exists.
• Keeping workspaces in sync — status, fetch, sync, and branch-sync.
• Project groups — several repositories in one folder, cloned into one workspace with a single workler add.
• Programmatic API — create, inspect, list, and remove workspaces from TypeScript or JavaScript.
• Agent skill — teach your coding agent to use Workler.