OpenParable
Skip to content
← Back to skills

Worktrees And Dev Servers

Development
worktrees-and-dev-servers

Worktrees And Dev Servers is an Agent Skill for development published in the pierrecomputer/pierre repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when working with the repo's moonx root:wt worktree helper, Pierre-managed worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures, or Chrome debug instances. Do not use this as a substitute for host-provided workspace isolation.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/pierrecomputer/pierre/blob/HEAD/.agents/skills/worktrees-and-dev-servers/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/worktrees-and-dev-servers, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Worktrees and Dev Servers

Pierre includes a repo-specific git worktree helper for local/manual parallelization outside host-managed agent workspaces. Managed Pierre worktrees live at:

~/pierre/pierre-worktrees/<slug>/

Each managed Pierre worktree owns a port offset so dev servers, E2E fixtures, and the Chrome remote-debug instance do not collide. The main clone keeps historical default ports; linked Pierre worktrees shift ports.

If you are already inside a Conductor, Codex, Claude, or other host-provided workspace, do not create another worktree unless the user explicitly asks for a Pierre-managed worktree. Still use this skill when you start repo dev servers or E2E fixtures, because the cleanup and port-offset rules apply to those scripts.

Worktree Commands

The wt suite is defined in scripts/wt.ts, exposed as the root:wt moon task, and manages only Pierre-managed worktrees:

moonx root:wt -- new <slug>    # create a worktree, allocate offset, pnpm install
moonx root:wt -- rm <slug>     # kill its processes, remove the worktree
moonx root:wt -- clean         # kill zombie servers on all managed worktree ports
moonx root:wt -- clean <slug>  # clean one managed worktree
moonx root:wt -- ps            # show per-worktree port status (LISTEN / -)
moonx root:wt -- list          # summary of managed + external worktrees

Port-binding moon tasks read the offset from <worktree>/.env.worktree via their envFile option. Before starting, dev tasks run scripts/run-dev.sh to kill any stale process bound to the target port.

Cleanup Contract

If you start dev servers, Playwright fixtures, or Chrome debug instances inside a worktree, run cleanup before completing your turn:

moonx root:wt -- clean <slug>

Use moonx root:wt -- clean when you do not know the slug or need to clean every managed worktree. Use moonx root:wt -- rm <slug> only when intentionally tearing down the worktree itself.