skills.rest
compozy
compozyOFFICIAL
Explore all skills by this author →
Website𝕏@compozyaiGitHub

eng-worktree-isolation

Allocates isolated Compozy runtime envelopes with unique ports and sockets for concurrent worktrees.

2.7k|171|Updated Mar 28, 2026
Search Tags:#QA#worktree#Runtime#port allocation#teardown#Concurrency#Isolation
One-click install
npx skills add https://github.com/compozy/compozy --skill eng-worktree-isolation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: eng-worktree-isolation
Source: https://github.com/compozy/compozy/tree/main/.agents/skills/eng/eng-worktree-isolation
Command: npx skills add https://github.com/compozy/compozy --skill eng-worktree-isolation

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Running multiple Compozy agents, QA runs, or parallel git worktrees on one machine causes runtime state collisions: shared COMPOZY_HOME directories, port conflicts on the daemon HTTP server, and clashing UDS or tmux sockets. This Skill provisions a dedicated runtime envelope per scenario so concurrent runs never interfere with each other or with the default ~/.compozy state.

Core Features & Use Cases

  • Isolated Runtime Allocation: Generates a unique COMPOZY_HOME directory, a free 127.0.0.1 TCP port, a unique UDS path, and a dedicated tmux bridge socket, emitted as shell export statements ready for eval.
  • Worktree-Aware Scoping: Optionally scopes the runtime home to Compozy/_worktrees/<slug>/.compozy when invoked from a parallel worktree, falling back to TMPDIR otherwise.
  • Verified Teardown: Enforces mandatory process cleanup via a targeted teardown helper that proves ownership of the envelope and reports TEARDOWN_ALL_CLEAN=true, without touching unrelated labs.
  • Use Case: An engineer creates a second worktree with make worktree-new SLUG=qa-fix, runs the allocator to get an isolated envelope, then executes E2E tests while another agent continues working in the main checkout.

Quick Start

Ask the agent to set up an isolated Compozy runtime for a parallel worktree or concurrent QA run, optionally providing a scenario slug for naming the envelope.

Frequently Asked Questions about eng-worktree-isolation

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run multiple Compozy agents on the same machine without conflicts?▼

Run the allocate-isolation.py script with a scenario slug to get a unique COMPOZY_HOME, HTTP port, UDS path, and tmux socket. Eval the printed export statements in your shell so every child process inherits the isolated envelope instead of the default ~/.compozy state.

How to isolate runtime state for parallel git worktrees?▼

Create the worktree with make worktree-new SLUG=<slug>, then invoke the allocator with --prefer-worktree from inside it. The runtime home is scoped to Compozy/_worktrees/<slug>/.compozy, keeping each checkout's daemon state fully separate.

When should I use worktree isolation versus the QA bootstrap skill?▼

Use worktree isolation for lightweight concurrent runs that only need separated runtime state. Prefer eng-qa-bootstrap for production-like QA, since it additionally provides a manifest, provider homes, browser policy, web proxy environment, and teardown evidence.

What happens if no free port is available during allocation?▼

The script binds port 0 on 127.0.0.1 to let the OS pick a free port, so exhaustion is rare. If allocation still fails, retry with a wider range; the skill instructs surfacing the busy ports and exiting rather than proceeding with a conflict.

Does cleanup delete the isolated COMPOZY_HOME directory?▼

Process teardown is mandatory and must report TEARDOWN_ALL_CLEAN=true, but the COMPOZY_HOME directory is retained for forensic inspection unless --purge is explicitly requested. Worktree-scoped .compozy directories are never purged because they belong to the user's checkout.

Related Skills

Explore More Software Engineering Skills→
jporrejporre
6

b1-add-worktree

Create a git worktree with a new branch, symlinks, and development port.

Community
Intermediate
compozycompozy
182

agh-worktree-isolation

Isolate AGH_HOME, daemon ports, and tmux sockets for concurrent agent worktrees.

Official
Intermediate
compozycompozy
182

agh-qa-bootstrap

Create an isolated deterministic AGH QA lab with a bootstrap manifest.

Official
Advanced
basnijholtbasnijholt
225

agent-cli-dev

Spawn parallel AI coding agents in isolated git worktrees.

Community
Advanced