Skip to main content
command CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/create_worktree_prompt.md
Open on GitHub

What 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-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

How to install create_worktree_prompt

Manually: put the files in place

.claude/commands/create_worktree_prompt.md

Call it with /create_worktree_prompt. For all projects use ~/.claude/commands/

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.

Similar slash commands

All slash commands for Git and GitHub →

From the same set20

The whole set →
t_metaprompt_workflow t_metaprompt_workflow generates structured Claude Code slash commands from a high-level task description while checking Anthropic docs. CX Codex +1 ★ 1,573repo stars scout-report-suggest-fast scout-report-suggest-fast hunts a described problem through a codebase and returns file paths, line numbers and a fix plan. It only reads. CX Codex ★ 1,573repo stars list_worktrees_prompt list_worktrees_prompt inspects git worktrees under the trees/ folder, detects active process ports, and outputs a runtime status report. CX Codex +1 ★ 1,573repo stars remove_worktree_prompt The remove_worktree_prompt command stops processes tied to a worktree, then removes the worktree and its Git branch. Check the branch name first: deletion cannot be undone. CX Codex +1 ★ 1,573repo stars worktree-manager-skill The worktree-manager-skill skill handles Git worktrees for parallel development, including creation, status checks, listing, and removal. CX Codex +1 ★ 1,573repo stars Video Processor Video Processor — a skill that handles video files from the agent: pull the audio track, convert to mp4 or webm, transcribe speech with Whisper. Useful when video files show up in a project. CX Codex +1 ★ 1,573repo stars Create New Skills Create New Skills guides the creation of custom Agent Skills for Claude Code. It designs SKILL.md files, configures activation triggers, and organizes helper scripts. CX Codex +1 ★ 1,573repo stars create-worktree-skill create-worktree-skill creates a separate Git worktree for a chosen branch and prepares its ports and configuration. Use it to run multiple project branches side by side. CX Codex +1 ★ 1,573repo stars

Project sponsors

Companies that keep this analytics open