create_worktree_prompt — Claude Code command for parallel git worktrees
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.
no license ★ 1,573 updated 2026-02-08
.claude/commands/create_worktree_prompt.mdWhat create_worktree_prompt 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.
What it helps with
- 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 for the agent
- Create a worktree for the branch
feature-observabilityand start it - Bring up a parallel copy from
experiment, pick the port offset yourself - Make a worktree for
fix-hookswith port offset 3
How to install create_worktree_prompt
Manually: put the files in place
.claude/commands/create_worktree_prompt.mdCall it with /create_worktree_prompt. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/create_worktree_prompt.mdCall it with /prompts:create_worktree_prompt. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/create_worktree_prompt.prompt.mdManually: put the files in place
.gemini/commands/create_worktree_prompt.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about create_worktree_prompt
How do I install create_worktree_prompt in Claude Code?
Place the command file at .claude/commands/create_worktree_prompt.md in your project. You then call it as /create_worktree_prompt.
What does create_worktree_prompt do?
It creates a git worktree under trees/<branch>, assigns separate ports and a separate database, installs dependencies and starts the server and client. The main repo stays untouched.
What does the command need to run?
bun must be on the system, otherwise dependency installation fails. If the target ports are busy, the command stops with an error — pass a different offset in that case.