# create_worktree_prompt

create_worktree_prompt sets up a git worktree under trees/ with separate ports, database and hooks, then starts the server and client. Useful for running several copies of the observability system side by side.

- command · `type=command` · Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI · ★ 1573 repo stars
- Author: disler
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/disler/claude-code-hooks-multi-agent-observability/tree/HEAD/.claude/commands/create_worktree_prompt.md
- Updated: 2026-02-08
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/commands/create-worktree-prompt

## What it does

The command takes a branch name and creates a worktree for it, then brings the services up. Ports are derived from an offset: the main repo keeps 4000 and 5173, the first worktree gets 4010 and 5183, the next one 4020 and 5193, and so on. Each worktree writes to its own `events.db`, so parallel instances do not collide.

It runs through a fixed sequence: validate arguments, check ports with `lsof`, run `git worktree add`, copy `.env`, write server and client config files, install dependencies with `bun install`, then launch `scripts/start-system.sh`. The start script kills whatever is already listening on those ports before starting services in the background.

Dependencies are installed automatically, but `bun` must be present. If a target port is taken, the command errors out and asks for a different offset. Output from the services is redirected to `/dev/null`, so after launch you work from the printed access URLs.

## Install

### Claude Code (native platform)

**Manually: put the files in place**
- File: `.claude/commands/create_worktree_prompt.md` — Call it with /create_worktree_prompt. For all projects use ~/.claude/commands/

### Codex

**Manually: put the files in place**
- File: `~/.codex/prompts/create_worktree_prompt.md` — Call it with /prompts:create_worktree_prompt. Codex marks this format deprecated in favour of skills

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/prompts/create_worktree_prompt.prompt.md`

### Gemini CLI

**Manually: put the files in place**
- File: `.gemini/commands/create_worktree_prompt.toml` — Gemini stores commands as TOML: the prompt text goes into the prompt field

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/disler/claude-code-hooks-multi-agent-observability/tree/HEAD/.claude/commands/create_worktree_prompt.md

## When to use it
- spin up a second copy of the project without touching the main one
- keep ports and databases apart across parallel instances
- create a branch and worktree in one command
- start server and client right after creating the worktree
- isolate hooks so events reach the correct server

## Example prompts
- Create a worktree for the branch `feature-observability` and start it
- Bring up a parallel copy from `experiment`, pick the port offset yourself
- Make a worktree for `fix-hooks` with port offset 3

## Similar
- [git-worktree-manager](https://affpapa.org/en/nevibecode/skills/git-worktree-manager.md) — skill · 581 installs
- [ce-worktree](https://affpapa.org/en/nevibecode/skills/ce-worktree.md) — skill · 3200 installs
- [git-worktree-isolation](https://affpapa.org/en/nevibecode/skills/git-worktree-isolation.md) — skill · 2300 installs
- [worktree-deliver](https://affpapa.org/en/nevibecode/commands/worktree-deliver.md) — command · 81 installs
- [todo-worktree](https://affpapa.org/en/nevibecode/commands/todo-worktree.md) — command · ★ 1357 repo stars
- [om-auto-create-pr-loop](https://affpapa.org/en/nevibecode/skills/om-auto-create-pr-loop.md) — skill · 4700 installs

From the same set: [disler/claude-code-hooks-multi-agent-observability](https://affpapa.org/en/nevibecode/by/disler/claude-code-hooks-multi-agent-observability.md) — 20 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
