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

agh-worktree-isolation

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

182|8|Updated Apr 4, 2026
Search Tags:#agent runtime#local-first#worktree isolation#SQLite lock#port deconfliction#tmux bridge#parallel QA
One-click install
npx skills add https://github.com/compozy/agh --skill agh-worktree-isolation
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: agh-worktree-isolation
Source: https://github.com/compozy/agh/tree/main/.agents/skills/agh/agh-worktree-isolation
Command: npx skills add https://github.com/compozy/agh --skill agh-worktree-isolation

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Prevents concurrent agent worktrees from deadlocking or corrupting shared local state by isolating AGH_HOME, daemon ports, and tmux-bridge socket paths.

Core Features & Use Cases

  • Isolated AGH runtime envelope: Allocates a unique AGH_HOME directory per scenario to avoid SQLite contention and cross-run interference.
  • Port and socket deconfliction: Picks free localhost TCP ports for the daemon and a unique UDS path, plus a dedicated tmux-bridge socket.
  • Concurrency-safety guardrails: Designed to be the low-level primitive beneath QA execution skills, blocking operations that would write to the default home or default ports when parallelism is signaled.

Quick Start

Ask an agent to create an isolated envelope for a parallel QA scenario by running: python3 .agents/skills/agh-worktree-isolation/scripts/allocate-isolation.py --slug "your-scenario-slug" and then source the printed export statements to run your QA inside the isolated environment.

Frequently Asked Questions about agh-worktree-isolation

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

FAQPage Schema
How do I prevent SQLite lock collisions when running parallel agents in separate git worktrees?▼

To prevent SQLite lock collisions during parallel agent execution, you must isolate the AGH_HOME directory per scenario, allocating a unique runtime path so each agent operates independently without cross-run interference.

What causes AGH agents to deadlock when running concurrent QA scenarios in different worktrees?▼

Agents deadlock because multiple concurrent worktrees share the default AGH_HOME, daemon ports, and tmux-bridge sockets, causing lock contention and port conflicts that freeze operations during parallel QA execution.

How do I allocate isolated environments for parallel agent QA runs?▼

Run the allocation script with a scenario slug, then source the printed export statements to set AGH_HOME, AGH_HTTP_PORT, AGH_UDS_PATH, and TMUX_BRIDGE_SOCKET for deterministic downstream QA execution.

Does port deconfliction automatically select free localhost ports for agent daemon communication?▼

Yes, port deconfliction automatically picks free localhost TCP ports for the daemon and designates a unique Unix domain socket path, ensuring deterministic and collision-free communication across parallel agent worktrees.

Do I need a dedicated tmux-bridge socket for each isolated agent worktree?▼

Yes, each isolated agent worktree requires a dedicated tmux-bridge socket to prevent concurrent terminal sessions from interfering, ensuring parallel QA operations remain deterministic and separated across worktrees.

Related Skills

Explore More Software Engineering Skills→
onchainengineeronchainengineer

dev-server-sandbox

Run isolated Unix dev-server instances with unique UNIX_ROOTs and dynamic ports.

Community
Intermediate
compozycompozy
182

agh-qa-bootstrap

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

Official
Advanced
devCharuzudevCharuzu

git-worktree-manager

Create Git worktrees with deterministic ports and synced environment files.

Community
Advanced
Fantasia1999Fantasia1999

git-worktree-manager

Manage Git worktrees with deterministic port allocation and safe cleanup.

Community
Advanced