# worktree-boot

[![ci](https://github.com/kanchingyg/worktree-boot/actions/workflows/ci.yml/badge.svg)](https://github.com/kanchingyg/worktree-boot/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/worktree-boot)](https://www.npmjs.com/package/worktree-boot)
[![JSR](https://jsr.io/badges/@kanchingyg/worktree-boot)](https://jsr.io/@kanchingyg/worktree-boot)
[![Rust](https://img.shields.io/badge/engine-Rust-dea584)](https://github.com/kanchingyg/worktree-boot)
[![license](https://img.shields.io/github/license/kanchingyg/worktree-boot)](https://github.com/kanchingyg/worktree-boot/blob/HEAD/LICENSE)

**One line:** `npx worktree-boot my-branch` (or `bunx worktree-boot my-branch`): `git worktree` + copy-on-write `node_modules` + shifted `.env` ports in about a second.

## Why

Plain `git worktree add` leaves out gitignored `.env` files, starts with an empty `node_modules`, and keeps identical `PORT=3000` values so parallel dev servers collide. Docker devcontainers isolate ports but cost gigabytes of RAM and slow boot times.

`worktree-boot` clones heavy folders using `cp --reflink=auto` on Linux and macOS when the filesystem supports it (falling back to a recursive copy otherwise, and using recursive copy on Windows). It copies `.env*`, shifts ports (`3000 -> 3001`, `5173 -> 5174`), and wires `LOCAL_LLM_URL` / `OLLAMA_HOST` for local LLM stacks. Provider API keys are **not** copied unless you pass `--propagate-api-keys` (CLI) or `propagateApiKeys: true` (MCP).

## Install

[Bun](https://bun.sh) / [npm](https://www.npmjs.com/package/worktree-boot):

```bash
bunx worktree-boot agent-2 --allow-write
npx worktree-boot agent-2 --allow-write

# or install in your project / globally
bun add -d worktree-boot
npm i -D worktree-boot
```

[JSR](https://jsr.io/@kanchingyg/worktree-boot):

```bash
bunx jsr add @kanchingyg/worktree-boot
npx jsr add @kanchingyg/worktree-boot
```

[Cargo (Rust native binary)](https://github.com/kanchingyg/worktree-boot):

```bash
cargo install --git https://github.com/kanchingyg/worktree-boot
```

The core engine is **Rust** (`src/lib.rs`, `src/main.rs`, `src/mcp.rs`). TypeScript under `src/*.ts` is included for `npx` / `bunx` / JSR usage and MCP bridge helpers.

## Quick start

```bash
npx worktree-boot agent-2 --allow-write
cd .worktrees/agent-2
npm run dev
```

```bash
npx worktree-boot list
npx worktree-boot teardown agent-2 --allow-write
npx worktree-boot agent-3 --dry-run   # preview paths, clones, and ports without writing
```

## MCP

```bash
npx worktree-boot --mcp --allow-write
bunx worktree-boot --mcp --allow-write
```

Add to your agent MCP config with `command: npx` and `args: ["-y", "worktree-boot", "--mcp", "--allow-write"]`.

## Ollama / OpenAI-compatible locals

Each worktree gets offset ports on `OLLAMA_HOST` and `LOCAL_LLM_URL` so you can run several coding agents against local inference without re-indexing or reinstalling dependencies.

## License

[MIT](./LICENSE)